feat: add graceful shutdown endpoint for UVM API server and update documentation

uvm/api_models.py

@@ -14,6 +14,10 @@ class HealthResponse(BaseModel):
     status: str = "ok"
 
 
+class ServerExitResponse(BaseModel):
+    status: str = "stopping"
+
+
 class InstallRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 

uvm/routers/exit.py

@@ -0,0 +1,35 @@
+"""Authenticated graceful shutdown endpoint for the UVM API server."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request, status
+
+from ..api_models import ServerExitResponse
+from ..app import Application
+from .dependencies import get_authorized_application
+
+
+router = APIRouter(tags=["server"])
+
+
+@router.post("/exit", response_model=ServerExitResponse, status_code=status.HTTP_202_ACCEPTED)
+def exit_server(
+    background_tasks: BackgroundTasks,
+    request: Request,
+    _application: Application = Depends(get_authorized_application),
+) -> ServerExitResponse:
+    """Stop the Uvicorn process after this response has been delivered."""
+    server = getattr(request.app.state, "uvicorn_server", None)
+    if server is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="server shutdown is unavailable outside uvm --serve",
+        )
+    background_tasks.add_task(_request_server_exit, server)
+    return ServerExitResponse()
+
+
+def _request_server_exit(server: Any) -> None:
+    server.should_exit = True

uvm/server.py

@@ -35,6 +35,7 @@ def create_api(application: Application | None = None, *, host: str | None = Non
         ) from error
 
     from .routers.health import router as health_router
+    from .routers.exit import router as exit_router
     from .routers.installation import router as installation_router
     from .routers.vms import router as vms_router
     from .routers.diagnostics import router as diagnostics_router
@@ -55,6 +56,7 @@ def create_api(application: Application | None = None, *, host: str | None = Non
         )
 
     api.include_router(health_router)
+    api.include_router(exit_router)
     api.include_router(installation_router)
     api.include_router(vms_router)
     api.include_router(diagnostics_router)
@@ -91,7 +93,10 @@ def run_server(application: Application, *, host: str, port: int) -> None:
     if settings.api_tls_cert is not None:
         options["ssl_certfile"] = str(settings.api_tls_cert)
         options["ssl_keyfile"] = str(settings.api_tls_key)
-    uvicorn.run(create_api(application, host=host), **options)
+    api = create_api(application, host=host)
+    server = uvicorn.Server(uvicorn.Config(api, **options))
+    api.state.uvicorn_server = server
+    server.run()
 
 
 def _is_loopback_host(host: str) -> bool: