base-deployment-controller 0.2.0__tar.gz → 0.4.0__tar.gz

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: base-deployment-controller
-Version: 0.2.0
+Version: 0.4.0
 Summary: REST API to control the basic operations of a deployment
 Author: Tknika
 License: Creative Commons Atribución-NoComercial (CC BY-NC)
@@ -108,13 +108,13 @@ curl http://localhost:8000/envs
 ```
 
 #### PUT /envs
-Actualiza variables de entorno. Usa `restart_services` (por defecto `true`) para controlar si se reinician los servicios afectados.
+Actualiza variables de entorno. Usa `recreate_services` (por defecto `true`) para controlar si se recrean los servicios afectados.
 
 ```bash
 # Actualización múltiple
 curl -X PUT http://localhost:8000/envs \
   -H "Content-Type: application/json" \
-  -d '{"variables": {"MCC": "214", "MNC": "07"}, "restart_services": false}'
+  -d '{"variables": {"MCC": "214", "MNC": "07"}, "recreate_services": false}'
 ```
 
 #### GET /containers

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/README.md

@@ -87,13 +87,13 @@ curl http://localhost:8000/envs
 ```
 
 #### PUT /envs
-Actualiza variables de entorno. Usa `restart_services` (por defecto `true`) para controlar si se reinician los servicios afectados.
+Actualiza variables de entorno. Usa `recreate_services` (por defecto `true`) para controlar si se recrean los servicios afectados.
 
 ```bash
 # Actualización múltiple
 curl -X PUT http://localhost:8000/envs \
   -H "Content-Type: application/json" \
-  -d '{"variables": {"MCC": "214", "MNC": "07"}, "restart_services": false}'
+  -d '{"variables": {"MCC": "214", "MNC": "07"}, "recreate_services": false}'
 ```
 
 #### GET /containers

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "base-deployment-controller"
-version = "0.2.0"
+version = "0.4.0"
 description = "REST API to control the basic operations of a deployment"
 readme = "README.md"
 requires-python = ">=3.8"

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/__init__.py

@@ -10,6 +10,7 @@ from .routers.api import APIRoutes
 from .routers.environment import EnvRoutes
 from .routers.container import ContainerRoutes
 from .services.status_event_manager import StatusEventManager
+from .services.deployment_status_monitor import DeploymentStatusMonitor
 from .routers.deployment import DeploymentRoutes
 from .builder import AppBuilder
 
@@ -65,8 +66,12 @@ def create_app(
     api_routes = APIRoutes()
     env_routes = EnvRoutes(config_service, task_manager)
     status_events = StatusEventManager(config_service)
+    deployment_status_monitor = DeploymentStatusMonitor(
+        config_service,
+        status_events=status_events,
+    )
     container_routes = ContainerRoutes(config_service, task_manager, status_events)
-    deployment_routes = DeploymentRoutes(config_service, task_manager)
+    deployment_routes = DeploymentRoutes(config_service, task_manager, deployment_status_monitor)
 
     app.include_router(api_routes.router)
     app.include_router(env_routes.router)

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/builder.py

@@ -6,6 +6,7 @@ from fastapi import APIRouter, FastAPI
 from .services.config import ConfigService
 from .services.task_manager import TaskManager
 from .services.status_event_manager import StatusEventManager
+from .services.deployment_status_monitor import DeploymentStatusMonitor
 from .routers.api import APIRoutes
 from .routers.environment import EnvRoutes
 from .routers.container import ContainerRoutes
@@ -81,11 +82,15 @@ class AppBuilder:
         config_service = ConfigService(self.compose_file, self.env_file)
         task_manager = TaskManager(ttl=3600)
         status_events = StatusEventManager(config_service)
+        deployment_status_monitor = DeploymentStatusMonitor(
+            config_service,
+            status_events=status_events,
+        )
         
         api_routes = APIRoutes()
         env_routes = EnvRoutes(config_service, task_manager)
         container_routes = ContainerRoutes(config_service, task_manager, status_events)
-        deployment_routes = DeploymentRoutes(config_service, task_manager)
+        deployment_routes = DeploymentRoutes(config_service, task_manager, deployment_status_monitor)
 
         app.include_router(api_routes.router)
         app.include_router(env_routes.router)

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/models/environment.py

@@ -23,10 +23,10 @@ class BulkEnvUpdateRequest(BaseModel):
     """Request to update multiple environment variables in bulk."""
 
     variables: dict[str, str] = Field(..., description="Variables to update")
-    restart_services: bool = Field(
+    recreate_services: bool = Field(
         default=True,
         description=(
-            "Whether to restart affected services after updating the variables."
+            "Whether to recreate affected services after updating the variables."
         ),
     )
 
@@ -37,6 +37,6 @@ class EnvUpdateResponse(BaseModel):
     success: bool = Field(..., description="Update success status")
     updated: list[str] = Field(..., description="List of updated variables")
     message: str = Field(..., description="Status message")
-    restarted_services: dict[str, bool] = Field(
-        default_factory=dict, description="Services restarted and their status"
+    recreated_services: dict[str, bool] = Field(
+        default_factory=dict, description="Services recreated and their status"
     )

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/models/events.py

@@ -1,11 +1,12 @@
 """
-Event models for container status streaming via SSE.
+Event models for container and deployment status streaming via SSE.
 """
 from datetime import datetime
 from enum import Enum
 from typing import Optional
 
 from pydantic import BaseModel, Field
+from .deployment import DeploymentStatus
 
 
 class ServiceState(str, Enum):
@@ -32,3 +33,11 @@ class ContainerStatusEvent(BaseModel):
     prev_state: Optional[ServiceState] = Field(None, description="Previous state if known")
     action: str = Field(..., description="Docker event action that triggered the state change")
     timestamp: datetime = Field(..., description="Event timestamp")
+
+
+class DeploymentStatusEvent(BaseModel):
+    """Deployment status change event for SSE streaming."""
+
+    status: DeploymentStatus = Field(..., description="Current deployment status")
+    previous_status: Optional[DeploymentStatus] = Field(None, description="Previous deployment status if known")
+    timestamp: datetime = Field(..., description="Event timestamp")

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/routers/deployment.py

@@ -5,15 +5,18 @@ Manages deployment-wide operations: status, up, stop, down, restart.
 import asyncio
 import json
 import logging
-from typing import AsyncIterator, Dict, Set
+from datetime import datetime, timezone
+from typing import AsyncIterator, Dict, Set, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import Response, StreamingResponse
 
 from ..models.deployment import DeploymentInfoResponse
 from ..models.environment import EnvVariable
+from ..models.events import DeploymentStatusEvent
 from ..models.task import TaskResponse, TaskDetail, TaskStatus
 from ..services.config import ConfigService
+from ..services.deployment_status_monitor import DeploymentStatusMonitor
 from ..services.task_manager import TaskManager
 
 logger = logging.getLogger(__name__)
@@ -25,6 +28,7 @@ class DeploymentRoutes:
 
     Manages deployment-wide operations:
     - GET /deployment - Get deployment status with metadata and env-vars
+    - GET /deployment/status - SSE stream of deployment status changes
     - POST /deployment/up - Start deployment (async)
     - POST /deployment/stop - Stop deployment (async)
     - POST /deployment/down - Down deployment (async)
@@ -36,23 +40,32 @@ class DeploymentRoutes:
     Args:
         config: Instance of `ConfigService` for Compose and Docker access.
         task_manager: Instance of `TaskManager` for async operations.
+        status_monitor: Instance of `DeploymentStatusMonitor` for status monitoring.
 
     Attributes:
         config: Injected configuration service.
         task_manager: Injected task manager service.
+        status_monitor: Injected deployment status monitor.
         router: Instance of `APIRouter` with /deployment endpoints.
     """
 
-    def __init__(self, config: ConfigService, task_manager: TaskManager) -> None:
+    def __init__(
+        self, 
+        config: ConfigService, 
+        task_manager: TaskManager,
+        status_monitor: DeploymentStatusMonitor,
+    ) -> None:
         """
         Initialize deployment routes.
 
         Args:
             config: Configuration service instance for dependency injection.
             task_manager: Task manager instance for dependency injection.
+            status_monitor: Deployment status monitor instance for dependency injection.
         """
         self.config = config
         self.task_manager = task_manager
+        self.status_monitor = status_monitor
         self.router = self._build_router()
 
     def _build_router(self) -> APIRouter:
@@ -71,6 +84,12 @@ class DeploymentRoutes:
             methods=["GET"],
             response_model=DeploymentInfoResponse,
         )
+        # GET /deployment/status - SSE stream of deployment status changes
+        router.add_api_route(
+            "/status",
+            self.stream_deployment_status,
+            methods=["GET"],
+        )
         # POST /deployment/up - start deployment
         router.add_api_route(
             "/up",
@@ -412,6 +431,72 @@ class DeploymentRoutes:
             },
         )
 
+    async def stream_deployment_status(self) -> StreamingResponse:
+        """
+        Stream deployment status changes via Server-Sent Events (SSE).
+
+        Monitors deployment status and sends updates only when the status changes.
+        Sends the current status immediately upon connection.
+
+        Returns:
+            StreamingResponse with SSE stream of deployment status updates.
+        """
+        logger.info("Client connected to deployment status stream")
+
+        async def event_generator() -> AsyncIterator[str]:
+            """Generate SSE events for deployment status changes."""
+            q: Optional[asyncio.Queue] = None
+            try:
+                # Subscribe and get current status
+                q, current_status = await self.status_monitor.subscribe()
+                
+                # Send current status immediately if available
+                if current_status:
+                    event = DeploymentStatusEvent(
+                        status=current_status,
+                        previous_status=None,
+                        timestamp=datetime.now(timezone.utc),
+                    )
+                    yield f"data: {event.model_dump_json()}\n\n"
+                    logger.debug(f"Sent initial deployment status: {current_status}")
+
+                # Stream status changes
+                while True:
+                    try:
+                        # Get next event from queue (with timeout to allow cancellation)
+                        event = await asyncio.wait_for(q.get(), timeout=5.0)
+                        yield f"data: {event.model_dump_json()}\n\n"
+                        logger.debug(f"Sent deployment status change: {event.status}")
+                    except asyncio.TimeoutError:
+                        # Send keep-alive comment to prevent connection timeout
+                        yield ": keep-alive\n\n"
+                    except asyncio.CancelledError:
+                        logger.info("Deployment status stream cancelled by client")
+                        break
+                    except Exception as e:
+                        logger.error(f"Error in deployment status stream: {e}")
+                        yield f"event: error\ndata: {json.dumps({'error': str(e)})}\n\n"
+                        break
+
+            except Exception as e:
+                logger.error(f"Error subscribing to deployment status: {e}")
+                yield f"event: error\ndata: {json.dumps({'error': str(e)})}\n\n"
+            finally:
+                # Unsubscribe when client disconnects
+                if q is not None:
+                    await self.status_monitor.unsubscribe(q)
+                logger.info("Client disconnected from deployment status stream")
+
+        return StreamingResponse(
+            event_generator(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
     def _execute_compose_up(self, task_id: str) -> None:
         """
         Execute docker compose up.

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/routers/environment.py

@@ -30,7 +30,7 @@ class EnvRoutes:
 
     Provides endpoints for retrieving and updating environment variables
     defined in the compose.yaml x-env-vars schema. Updates are async when
-    services need to be restarted.
+    services need to be recreated.
 
     Args:
         config: Instance of `ConfigService` for file access and validation.
@@ -134,11 +134,11 @@ class EnvRoutes:
         """
         Update environment variables in .env file asynchronously.
 
-        When restart_services is True, the operation runs asynchronously
+        When recreate_services is True, the operation runs asynchronously
         and returns 202 Accepted with a task_id.
 
         Args:
-            request: Bulk update request with variables and restart flag.
+            request: Bulk update request with variables and recreate flag.
             fastapi_request: FastAPI request object (for building Location header).
 
         Returns:
@@ -176,11 +176,11 @@ class EnvRoutes:
 
             logger.info(f"Updating {len(updates)} environment variables")
 
-            # Create async task for update + restart
+            # Create async task for update + recreate
             task_id = await self.task_manager.create_task(
                 operation="env_update",
                 func=lambda: self._execute_env_update(
-                    task_id, updates, request.restart_services
+                    task_id, updates, request.recreate_services
                 ),
             )
 
@@ -287,10 +287,10 @@ class EnvRoutes:
         self,
         task_id: str,
         updates: dict[str, str],
-        restart_services: bool,
+        recreate_services: bool,
     ) -> EnvUpdateResponse:
         """
-        Execute environment variable update with optional service restart.
+        Execute environment variable update with optional service recreation.
 
         Runs in thread executor. TaskManager auto-manages state transitions:
         PENDING -> RUNNING (on start) -> COMPLETED (success) or FAILED (exception).
@@ -299,13 +299,13 @@ class EnvRoutes:
         Args:
             task_id: Task identifier (for logging).
             updates: Dict of variables to update.
-            restart_services: Whether to restart affected services.
+            recreate_services: Whether to recreate affected services.
 
         Returns:
             EnvUpdateResponse with update results.
 
         Raises:
-            Exception: On update/restart failure. Message stored in task.error.
+            Exception: On update/recreate failure. Message stored in task.error.
         """
         try:
             # Update .env file
@@ -315,20 +315,20 @@ class EnvRoutes:
             # Build updated variables list for response
             updated_var_names = list(updates.keys())
 
-            # Restart services if requested
-            restart_results: dict[str, bool] = {}
-            if restart_services:
-                # Compute affected services and restart via ConfigService
+            # Recreate services if requested
+            recreate_results: dict[str, bool] = {}
+            if recreate_services:
+                # Compute affected services and recreate via ConfigService
                 affected_services = self.config.get_affected_services(updated_var_names)
-                logger.info(f"[{task_id}] Restarting {len(affected_services)} affected services")
-                restart_results = self.config.restart_services(affected_services)
+                logger.info(f"[{task_id}] Recreating {len(affected_services)} affected services")
+                recreate_results = self.config.recreate_services(affected_services)
 
             logger.info(f"[{task_id}] Environment update completed successfully")
             return EnvUpdateResponse(
                 success=True,
                 message=f"Updated {len(updates)} environment variables",
                 updated=updated_var_names,
-                restarted_services=restart_results,
+                recreated_services=recreate_results,
             )
         except Exception as e:
             logger.error(f"[{task_id}] Error executing environment update: {e}")
@@ -336,7 +336,7 @@ class EnvRoutes:
                 success=False,
                 message=f"Failed to update environment variables: {str(e)}",
                 updated=[],
-                restarted_services={},
+                recreated_services={},
             )
 
     # Service-state updates removed; tasks no longer track per-service states.

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/services/config.py

@@ -326,15 +326,15 @@ class ConfigService:
             affected_services.update(services)
         return list(affected_services)
 
-    def restart_services(self, service_names: List[str]) -> Dict[str, bool]:
+    def recreate_services(self, service_names: List[str]) -> Dict[str, bool]:
         """
-        Restart specified Docker services/containers.
+        Recreate specified Docker services/containers.
 
         Args:
-            service_names: List of service names from compose.yaml to restart.
+            service_names: List of service names from compose.yaml to recreate.
 
         Returns:
-            Dict mapping service names to restart success status (True/False).
+            Dict mapping service names to recreate success status (True/False).
         """
         results: Dict[str, bool] = {}
 
@@ -353,23 +353,26 @@ class ConfigService:
 
                 try:
                     if client.container.exists(container_name):
-                        # Only restart if container exists
+                        # Only recreate if container exists
                         container_inspect = client.container.inspect(container_name)
                         if container_inspect.state.status == "running":
-                            client.container.restart(container_name)
+                            # Recreate service container to apply environment changes.
+                            # Equivalent intent to: docker compose rm -f -s <service> && docker compose up -d <service>
+                            client.compose.rm(services=[service_name], stop=True)
+                            client.compose.up(detach=True, services=[service_name])
                             results[service_name] = True
                         else:
-                            # Container exists but not running, don't restart
+                            # Container exists but not running, don't recreate
                             results[service_name] = False
                     else:
-                        # Container doesn't exist, can't restart
+                        # Container doesn't exist, can't recreate
                         results[service_name] = False
                 except Exception as e:
-                    logger.error(f"Error restarting service {service_name}: {e}")
+                    logger.error(f"Error recreating service {service_name}: {e}")
                     results[service_name] = False
 
         except Exception as e:
-            logger.error(f"Error in restart_services: {e}")
+            logger.error(f"Error in recreate_services: {e}")
 
         return results
 

base_deployment_controller-0.4.0/src/base_deployment_controller/services/deployment_status_monitor.py

@@ -0,0 +1,278 @@
+"""
+DeploymentStatusMonitor: on-demand deployment status monitor with SSE subscribers.
+
+Monitors deployment status changes by polling get_deployment_status at regular intervals
+and broadcasts changes to subscribed SSE clients. Starts when the first subscriber connects
+and stops when there are no subscribers.
+"""
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Set
+
+from ..models.deployment import DeploymentStatus
+from ..models.events import DeploymentStatusEvent, ServiceState
+from ..services.config import ConfigService
+from ..services.status_event_manager import StatusEventManager
+
+logger = logging.getLogger(__name__)
+
+
+class DeploymentStatusMonitor:
+    """
+    Manages deployment status monitoring and broadcasts status change events
+    to subscribed SSE clients. Starts when the first subscriber connects and stops
+    when there are no subscribers.
+    
+    Uses asyncio to process container events without blocking the event loop.
+    """
+
+    def __init__(
+        self,
+        config: ConfigService,
+        status_events: StatusEventManager,
+        error_backoff_seconds: float = 0.25,
+    ) -> None:
+        """
+        Initialize the deployment status monitor.
+        
+        Args:
+            config: ConfigService instance for accessing deployment status.
+            status_events: Shared StatusEventManager (single Docker events subscription).
+            error_backoff_seconds: Sleep time after errors in the event loop.
+        """
+        self.config = config
+        self.status_events = status_events
+        self._task: Optional[asyncio.Task] = None
+        self._subscribers: List[asyncio.Queue] = []
+        self._lock = asyncio.Lock()
+        self._last_status: Optional[DeploymentStatus] = None
+        self._error_backoff_seconds = error_backoff_seconds
+        self._container_states: Dict[str, ServiceState] = {}
+        self._relevant_containers: Set[str] = set()
+        self._docker_subscriber_q = None
+
+        services = self.config.compose_services or {}
+        for service_name, service_config in services.items():
+            container_name = service_config.get("container_name", service_name)
+            self._relevant_containers.add(container_name)
+
+        logger.info(
+            f"DeploymentStatusMonitor: initialized for {len(self._relevant_containers)} containers"
+        )
+
+    async def _ensure_started(self) -> None:
+        """Ensure the monitor task is running."""
+        async with self._lock:
+            if self._task and not self._task.done():
+                return
+            # Start monitor task
+            self._task = asyncio.create_task(self._monitor_loop())
+            logger.debug("DeploymentStatusMonitor: monitor started")
+
+    async def _maybe_stop(self) -> None:
+        """Stop the monitor if there are no subscribers."""
+        async with self._lock:
+            if self._subscribers:
+                return
+            if self._task and not self._task.done():
+                self._task.cancel()
+                try:
+                    await self._task
+                except asyncio.CancelledError:
+                    pass
+                self._task = None
+                logger.info("DeploymentStatusMonitor: monitor stopped")
+
+    async def subscribe(self) -> tuple[asyncio.Queue, Optional[DeploymentStatus]]:
+        """
+        Add a new subscriber and ensure the monitor is running.
+        
+        Returns:
+            Tuple of (queue for receiving events, current deployment status).
+            The current status is returned immediately so the client has the initial state.
+        """
+        q: asyncio.Queue = asyncio.Queue()
+
+        # Ensure we have a snapshot for immediate, correct initial state.
+        if self._last_status is None:
+            await self._refresh_snapshot()
+
+        async with self._lock:
+            self._subscribers.append(q)
+            current_status = self._last_status
+
+        await self._ensure_started()
+        return q, current_status
+
+    async def _refresh_snapshot(self) -> None:
+        """Build an initial container state snapshot via Docker inspection."""
+
+        def _snapshot_sync() -> Dict[str, ServiceState]:
+            services = self.config.compose_services or {}
+            if not services:
+                return {}
+
+            client = self.config.get_docker_client()
+            snapshot: Dict[str, ServiceState] = {}
+            for service_name, service_config in services.items():
+                container_name = service_config.get("container_name", service_name)
+                try:
+                    if not client.container.exists(container_name):
+                        snapshot[container_name] = ServiceState.REMOVED
+                        continue
+                    inspect = client.container.inspect(container_name)
+                    if getattr(inspect.state, "status", None) == "running":
+                        snapshot[container_name] = ServiceState.STARTED
+                    else:
+                        snapshot[container_name] = ServiceState.STOPPED
+                except Exception:
+                    snapshot[container_name] = ServiceState.ERROR
+            return snapshot
+
+        async with self._lock:
+            # Avoid doing expensive snapshots repeatedly.
+            if self._last_status is not None:
+                return
+
+        snapshot = await asyncio.to_thread(_snapshot_sync)
+        new_status = self._compute_deployment_status(snapshot)
+
+        async with self._lock:
+            self._container_states = snapshot
+            self._last_status = new_status
+            logger.info(f"DeploymentStatusMonitor: initial snapshot status={new_status}")
+
+    def _compute_deployment_status(self, states: Dict[str, ServiceState]) -> DeploymentStatus:
+        """Compute deployment status from relevant container states."""
+        if not self._relevant_containers:
+            return DeploymentStatus.UNKNOWN
+
+        started = 0
+        stopped = 0
+        transitional = 0
+        unknown = 0
+        total = len(self._relevant_containers)
+
+        for name in self._relevant_containers:
+            state = states.get(name)
+            if state in (ServiceState.STARTED, ServiceState.STARTING):
+                started += 1
+            elif state in (ServiceState.STOPPED, ServiceState.REMOVED, ServiceState.NOT_STARTED):
+                stopped += 1
+            elif state in (ServiceState.CREATING, ServiceState.STOPPING, ServiceState.PULLING, ServiceState.PULLED, ServiceState.REMOVED):
+                transitional += 1
+            elif state is None:
+                unknown += 1
+            else:
+                # Error/other states
+                logger.warning(f"DeploymentStatusMonitor: container '{name}' in state '{state}' treated as unknown")
+                unknown += 1
+
+        if started == total:
+            return DeploymentStatus.RUNNING
+        if stopped == total:
+            return DeploymentStatus.STOPPED
+        if started == 0 and stopped == 0 and unknown == total:
+            return DeploymentStatus.UNKNOWN
+        return DeploymentStatus.PARTIALLY_RUNNING
+
+    async def unsubscribe(self, q: asyncio.Queue) -> None:
+        """
+        Remove subscriber and stop monitor if none left.
+        
+        Args:
+            q: The queue to unsubscribe.
+        """
+        async with self._lock:
+            if q in self._subscribers:
+                self._subscribers.remove(q)
+        await self._maybe_stop()
+
+    async def _broadcast(self, event: DeploymentStatusEvent) -> None:
+        """
+        Broadcast an event to all subscribers.
+        
+        Args:
+            event: The deployment status event to broadcast.
+        """
+        # Snapshot subscribers to avoid holding lock while putting
+        async with self._lock:
+            subscribers = list(self._subscribers)
+        
+        for q in subscribers:
+            try:
+                await asyncio.wait_for(q.put(event), timeout=0.1)
+            except asyncio.TimeoutError:
+                logger.warning("DeploymentStatusMonitor: timeout broadcasting to subscriber")
+            except Exception as e:
+                logger.error(f"DeploymentStatusMonitor: error broadcasting to subscriber: {e}")
+
+    async def _monitor_loop(self) -> None:
+        """
+        Background task: process container events and broadcast deployment status changes.
+        
+        Runs continuously while there are subscribers.
+        Only broadcasts when the computed deployment status changes.
+        """
+        try:
+            logger.debug("DeploymentStatusMonitor: starting monitor loop (docker events)")
+
+            # Internal subscription to the shared Docker events manager.
+            self._docker_subscriber_q = self.status_events.subscribe()
+
+            while True:
+                try:
+                    container_event = await self.status_events.get_event(self._docker_subscriber_q)
+                    name = container_event.container_name
+
+                    if name not in self._relevant_containers:
+                        await asyncio.sleep(0)
+                        continue
+
+                    async with self._lock:
+                        self._container_states[name] = container_event.state
+                        current_status = self._compute_deployment_status(self._container_states)
+                        prev_status = self._last_status
+
+                        if current_status == prev_status:
+                            continue
+
+                        self._last_status = current_status
+
+                    logger.info(
+                        f"DeploymentStatusMonitor: status changed from {prev_status} to {current_status}"
+                    )
+
+                    event = DeploymentStatusEvent(
+                        status=current_status,
+                        previous_status=prev_status,
+                        timestamp=datetime.now(timezone.utc),
+                    )
+                    await self._broadcast(event)
+
+                except asyncio.CancelledError:
+                    logger.debug("DeploymentStatusMonitor: monitor loop cancelled")
+                    raise
+                except Exception as e:
+                    logger.error(
+                        f"DeploymentStatusMonitor: error processing docker events: {e}",
+                        exc_info=True,
+                    )
+                    await asyncio.sleep(self._error_backoff_seconds)
+                    
+        except asyncio.CancelledError:
+            logger.debug("DeploymentStatusMonitor: monitor loop exiting")
+        except Exception as e:
+            logger.error(
+                f"DeploymentStatusMonitor: fatal error in monitor loop: {e}",
+                exc_info=True
+            )
+        finally:
+            # Ensure we unsubscribe from Docker events.
+            try:
+                if self._docker_subscriber_q is not None:
+                    self.status_events.unsubscribe(self._docker_subscriber_q)
+            except Exception:
+                pass
+            logger.debug("DeploymentStatusMonitor: monitor loop stopped")

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller/services/status_event_manager.py

@@ -99,7 +99,7 @@ class StatusEventManager:
     def _monitor_loop(self) -> None:
         """Background thread: listen to Docker events and broadcast mapped state events."""
         try:
-            logger.info("StatusEventManager: starting Docker event monitor")
+            logger.debug("StatusEventManager: starting Docker event monitor")
             docker = self.config.get_docker_client()
             action_to_state = {
                 "kill": ServiceState.STOPPING,
@@ -113,10 +113,10 @@ class StatusEventManager:
                 "build": ServiceState.CREATING,
             }
             
-            logger.info("StatusEventManager: listening to docker.system.events()")
+            logger.debug("StatusEventManager: listening to docker.system.events()")
             for event in docker.system.events(filters={"type": "container"}):
                 if self._stop_event.is_set():
-                    logger.info("StatusEventManager: stop event received, breaking")
+                    logger.debug("StatusEventManager: stop event received, breaking")
                     break
                 try:
                     action = getattr(event, "action", "").lower()
@@ -136,7 +136,7 @@ class StatusEventManager:
                     prev_state = self._last_state.get(name)
                     self._last_state[name] = new_state
                     
-                    logger.info(f"StatusEventManager: {name} state={new_state} (action={action})")
+                    logger.debug(f"StatusEventManager: {name} state={new_state} (action={action})")
                     
                     ev = ContainerStatusEvent(
                         container_name=name,

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: base-deployment-controller
-Version: 0.2.0
+Version: 0.4.0
 Summary: REST API to control the basic operations of a deployment
 Author: Tknika
 License: Creative Commons Atribución-NoComercial (CC BY-NC)
@@ -108,13 +108,13 @@ curl http://localhost:8000/envs
 ```
 
 #### PUT /envs
-Actualiza variables de entorno. Usa `restart_services` (por defecto `true`) para controlar si se reinician los servicios afectados.
+Actualiza variables de entorno. Usa `recreate_services` (por defecto `true`) para controlar si se recrean los servicios afectados.
 
 ```bash
 # Actualización múltiple
 curl -X PUT http://localhost:8000/envs \
   -H "Content-Type: application/json" \
-  -d '{"variables": {"MCC": "214", "MNC": "07"}, "restart_services": false}'
+  -d '{"variables": {"MCC": "214", "MNC": "07"}, "recreate_services": false}'
 ```
 
 #### GET /containers

{base_deployment_controller-0.2.0 → base_deployment_controller-0.4.0}/src/base_deployment_controller.egg-info/SOURCES.txt

@@ -22,9 +22,11 @@ src/base_deployment_controller/routers/deployment.py
 src/base_deployment_controller/routers/environment.py
 src/base_deployment_controller/services/__init__.py
 src/base_deployment_controller/services/config.py
+src/base_deployment_controller/services/deployment_status_monitor.py
 src/base_deployment_controller/services/status_event_manager.py
 src/base_deployment_controller/services/task_manager.py
 tests/test_api.py
 tests/test_containers.py
 tests/test_deployment.py
-tests/test_envs.py
+tests/test_envs.py
+tests/test_status_event_manager.py

base_deployment_controller-0.4.0/tests/test_deployment.py

@@ -0,0 +1,102 @@
+"""
+Test cases for the Deployment endpoints (/deployment).
+
+Tests the full deployment lifecycle:
+- Deploy UP with real-time SSE monitoring
+- Deploy DOWN with real-time SSE monitoring
+"""
+import time
+import threading
+from tests.utils import stream_task_updates, monitor_deployment_status
+
+
+class TestDeploymentEndpoints:
+    """Deployment endpoint tests with SSE monitoring."""
+
+    def test_deployment_lifecycle_with_sse_monitoring(self, api_client, api_url, api_server, check_dependencies):
+        """
+        Test complete deployment lifecycle with real-time SSE monitoring.
+        
+        Sequence:
+        1. Start background monitor for /deployment/status
+        2. POST /deployment/up to start deployment
+        3. Monitor SSE stream to track container state transitions
+        4. Verify all containers reach STARTED state
+        5. POST /deployment/down to down deployment
+        6. Monitor SSE stream for shutdown progression
+        7. Verify all containers reach REMOVED state
+        """
+        print("\n=== DEPLOYMENT LIFECYCLE TEST ===\n")
+
+        # Start background monitor for overall deployment status
+        stop_monitor = threading.Event()
+        monitor_thread = threading.Thread(
+            target=monitor_deployment_status, 
+            args=(api_url, stop_monitor),
+            daemon=True
+        )
+        monitor_thread.start()
+        
+        # Give monitor a moment to connect
+        time.sleep(1)
+        
+        try:
+            # PHASE 1: Start deployment
+            print("PHASE 1: Starting deployment (compose up)...")
+            resp_up = api_client.post(f"{api_url}/deployment/up")
+            
+            assert resp_up.status_code == 202, "UP should return 202 Accepted"
+            data_up = resp_up.json()
+            assert "task_id" in data_up, "Response should contain task_id"
+            assert data_up.get("status") == "running", "Initial status should be 'running'"
+            
+            task_id_up = data_up["task_id"]
+            sse_endpoint_up = f"/deployment/tasks/{task_id_up}/stream"
+            
+            # Stream and monitor UP progress
+            print(f"Monitoring UP task {task_id_up[:8]}... via SSE...")
+            up_start_time = time.monotonic()
+            final_state_up = stream_task_updates(
+                api_url, task_id_up, sse_endpoint_up, timeout=120
+            )
+            up_elapsed = time.monotonic() - up_start_time
+            print(f"UP completed in {up_elapsed:.2f} seconds")
+            
+            # Verify all containers are in STARTED state
+            print(f"Final UP task: {final_state_up}")
+            assert final_state_up.get("task_status") == "completed", "UP task should be completed"
+            assert final_state_up.get("operation") == "up"
+            
+            time.sleep(2)  # Give containers time to settle
+            
+            # PHASE 2: Stop deployment
+            print("\nPHASE 2: Stopping deployment (compose down)...")
+            resp_down = api_client.post(f"{api_url}/deployment/down")
+            
+            assert resp_down.status_code == 202, "DOWN should return 202 Accepted"
+            data_down = resp_down.json()
+            assert "task_id" in data_down, "Response should contain task_id"
+            
+            task_id_down = data_down["task_id"]
+            sse_endpoint_down = f"/deployment/tasks/{task_id_down}/stream"
+            
+            # Stream and monitor DOWN progress
+            print(f"Monitoring DOWN task {task_id_down[:8]}... via SSE...")
+            down_start_time = time.monotonic()
+            final_state_down = stream_task_updates(
+                api_url, task_id_down, sse_endpoint_down, timeout=120
+            )
+            down_elapsed = time.monotonic() - down_start_time
+            print(f"DOWN completed in {down_elapsed:.2f} seconds")
+            
+            # Verify all containers are in REMOVED state
+            print(f"Final DOWN task: {final_state_down}")
+            assert final_state_down.get("task_status") == "completed", "DOWN task should be completed"
+            assert final_state_down.get("operation") == "down"
+            
+            print("\n✓ Deployment lifecycle test passed")
+            
+        finally:
+            # Stop the monitor thread
+            stop_monitor.set()
+            monitor_thread.join(timeout=5)

base_deployment_controller-0.4.0/tests/test_status_event_manager.py

@@ -0,0 +1,138 @@
+"""
+Unit tests for StatusEventManager and ContainerStatusEvent.
+"""
+import pytest
+from datetime import datetime, timezone
+from queue import Queue
+
+from src.base_deployment_controller.models.events import ContainerStatusEvent, ServiceState
+from src.base_deployment_controller.services.status_event_manager import StatusEventManager
+from src.base_deployment_controller.services.config import ConfigService
+
+
+def test_container_status_event_creation():
+    """Test that ContainerStatusEvent can be created and serialized."""
+    event = ContainerStatusEvent(
+        container_name="test-container",
+        state=ServiceState.STARTED,
+        prev_state=ServiceState.STARTING,
+        action="start",
+        timestamp=datetime.now(timezone.utc)
+    )
+    
+    assert event.container_name == "test-container"
+    assert event.state == ServiceState.STARTED
+    assert event.prev_state == ServiceState.STARTING
+    assert event.action == "start"
+    assert event.timestamp is not None
+    
+    # Test JSON serialization
+    json_str = event.model_dump_json()
+    assert "test-container" in json_str
+    assert "started" in json_str.lower()
+    print(f"✓ Event JSON: {json_str}")
+
+
+def test_container_status_event_json_format():
+    """Test that JSON matches expected SSE format."""
+    event = ContainerStatusEvent(
+        container_name="web",
+        state=ServiceState.STOPPED,
+        prev_state=None,
+        action="stop",
+        timestamp=datetime(2026, 1, 20, 10, 30, 0, tzinfo=timezone.utc)
+    )
+    
+    json_str = event.model_dump_json()
+    
+    # Should be valid JSON
+    import json
+    data = json.loads(json_str)
+    
+    assert data["container_name"] == "web"
+    assert data["state"] == "stopped"
+    assert data["action"] == "stop"
+    assert data["prev_state"] is None
+    
+    print(f"✓ JSON structure is valid: {json_str}")
+
+
+def test_status_event_manager_creation():
+    """Test that StatusEventManager can be instantiated."""
+    config = ConfigService("data/compose.yaml", "data/.env")
+    manager = StatusEventManager(config)
+    
+    assert manager is not None
+    assert manager._thread is None  # Not started yet
+    assert len(manager._subscribers) == 0
+    print("✓ StatusEventManager created successfully")
+
+
+def test_status_event_manager_subscribe_unsubscribe():
+    """Test subscribe/unsubscribe functionality."""
+    config = ConfigService("data/compose.yaml", "data/.env")
+    manager = StatusEventManager(config)
+    
+    # Subscribe
+    q1 = manager.subscribe()
+    assert isinstance(q1, Queue)
+    assert len(manager._subscribers) == 1
+    print("✓ First subscriber connected")
+    
+    # Subscribe again
+    q2 = manager.subscribe()
+    assert len(manager._subscribers) == 2
+    print("✓ Second subscriber connected")
+    
+    # Unsubscribe first
+    manager.unsubscribe(q1)
+    assert len(manager._subscribers) == 1
+    print("✓ First subscriber disconnected")
+    
+    # Unsubscribe second
+    manager.unsubscribe(q2)
+    assert len(manager._subscribers) == 0
+    print("✓ Second subscriber disconnected")
+
+
+def test_status_event_manager_broadcast():
+    """Test that events are broadcast to all subscribers."""
+    config = ConfigService("data/compose.yaml", "data/.env")
+    manager = StatusEventManager(config)
+    
+    # Subscribe two clients
+    q1 = manager.subscribe()
+    q2 = manager.subscribe()
+    
+    # Broadcast an event
+    event = ContainerStatusEvent(
+        container_name="test",
+        state=ServiceState.STARTED,
+        prev_state=None,
+        action="start",
+        timestamp=datetime.now(timezone.utc)
+    )
+    manager._broadcast(event)
+    
+    # Both queues should receive the event
+    received1 = q1.get(timeout=1)
+    received2 = q2.get(timeout=1)
+    
+    assert received1.container_name == "test"
+    assert received2.container_name == "test"
+    print("✓ Events broadcast to all subscribers")
+    
+    manager.unsubscribe(q1)
+    manager.unsubscribe(q2)
+
+
+if __name__ == "__main__":
+    print("Running StatusEventManager tests...\n")
+    
+    test_container_status_event_creation()
+    test_container_status_event_json_format()
+    test_status_event_manager_creation()
+    test_status_event_manager_subscribe_unsubscribe()
+    test_status_event_manager_broadcast()
+    
+    print("\n✓ All tests passed!")

base_deployment_controller-0.2.0/tests/test_deployment.py

@@ -1,76 +0,0 @@
-"""
-Test cases for the Deployment endpoints (/deployment).
-
-Tests the full deployment lifecycle:
-- Deploy UP with real-time SSE monitoring
-- Deploy DOWN with real-time SSE monitoring
-"""
-import time
-from tests.utils import stream_task_updates
-
-
-class TestDeploymentEndpoints:
-    """Deployment endpoint tests with SSE monitoring."""
-
-    def test_deployment_lifecycle_with_sse_monitoring(self, api_client, api_url, api_server, check_dependencies):
-        """
-        Test complete deployment lifecycle with real-time SSE monitoring.
-        
-        Sequence:
-        1. POST /deployment/up to start deployment
-        2. Monitor SSE stream to track container state transitions
-        3. Verify all containers reach STARTED state
-        4. POST /deployment/down to down deployment
-        5. Monitor SSE stream for shutdown progression
-        6. Verify all containers reach REMOVED state
-        """
-        print("\n=== DEPLOYMENT LIFECYCLE TEST ===\n")
-        
-        # PHASE 1: Start deployment
-        print("PHASE 1: Starting deployment (compose up)...")
-        resp_up = api_client.post(f"{api_url}/deployment/up")
-        
-        assert resp_up.status_code == 202, "UP should return 202 Accepted"
-        data_up = resp_up.json()
-        assert "task_id" in data_up, "Response should contain task_id"
-        assert data_up.get("status") == "running", "Initial status should be 'running'"
-        
-        task_id_up = data_up["task_id"]
-        sse_endpoint_up = f"/deployment/tasks/{task_id_up}/stream"
-        
-        # Stream and monitor UP progress
-        print(f"Monitoring UP task {task_id_up[:8]}... via SSE...")
-        final_state_up = stream_task_updates(
-            api_url, task_id_up, sse_endpoint_up, timeout=120
-        )
-        
-        # Verify all containers are in STARTED state
-        print(f"Final UP task: {final_state_up}")
-        assert final_state_up.get("task_status") == "completed", "UP task should be completed"
-        assert final_state_up.get("operation") == "up"
-        
-        time.sleep(2)  # Give containers time to settle
-        
-        # PHASE 2: Stop deployment
-        print("\nPHASE 2: Stopping deployment (compose down)...")
-        resp_down = api_client.post(f"{api_url}/deployment/down")
-        
-        assert resp_down.status_code == 202, "DOWN should return 202 Accepted"
-        data_down = resp_down.json()
-        assert "task_id" in data_down, "Response should contain task_id"
-        
-        task_id_down = data_down["task_id"]
-        sse_endpoint_down = f"/deployment/tasks/{task_id_down}/stream"
-        
-        # Stream and monitor DOWN progress
-        print(f"Monitoring DOWN task {task_id_down[:8]}... via SSE...")
-        final_state_down = stream_task_updates(
-            api_url, task_id_down, sse_endpoint_down, timeout=120
-        )
-        
-        # Verify all containers are in REMOVED state
-        print(f"Final DOWN task: {final_state_down}")
-        assert final_state_down.get("task_status") == "completed", "DOWN task should be completed"
-        assert final_state_down.get("operation") == "down"
-        
-        print("\n✓ Deployment lifecycle test passed")