MAESTRO: add health endpoint

backend/app/main.py

@@ -4,6 +4,7 @@ from app.core.config import get_settings
 from app.middleware.rate_limiter import RateLimiterMiddleware, SlidingWindowRateLimiter
 from app.routers.analysis import router as analysis_router
 from app.routers.captcha import router as captcha_router
+from app.routers.health import router as health_router
 from app.routers.tests import router as tests_router
 
 app = FastAPI(title="Web Header Analyzer API")
@@ -16,6 +17,7 @@ app.add_middleware(
 )
 app.include_router(analysis_router)
 app.include_router(captcha_router)
+app.include_router(health_router)
 app.include_router(tests_router)
 
 

backend/app/routers/health.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+import time
+import tomllib
+from importlib import metadata
+from pathlib import Path
+
+from fastapi import APIRouter
+
+from app.engine.scanner_registry import ScannerRegistry
+from app.schemas.health import HealthResponse
+
+router = APIRouter(prefix="/api", tags=["health"])
+
+_START_TIME = time.monotonic()
+_PROJECT_NAME = "web-header-analyzer-backend"
+
+
+@router.get("/health", response_model=HealthResponse)
+def health_check() -> HealthResponse:
+    status = "up"
+    scanner_count = 0
+
+    try:
+        registry = ScannerRegistry()
+        scanner_count = len(registry.list_tests())
+        if scanner_count == 0:
+            status = "degraded"
+    except Exception:
+        status = "down"
+        scanner_count = 0
+
+    return HealthResponse(
+        status=status,
+        version=_resolve_version(),
+        uptime=_uptime_seconds(),
+        scanner_count=scanner_count,
+    )
+
+
+def _uptime_seconds() -> float:
+    return max(0.0, time.monotonic() - _START_TIME)
+
+
+def _resolve_version() -> str:
+    env_version = os.getenv("WHA_VERSION", "").strip()
+    if env_version:
+        return env_version
+
+    try:
+        return metadata.version(_PROJECT_NAME)
+    except metadata.PackageNotFoundError:
+        pass
+
+    pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if pyproject_path.exists():
+        try:
+            data = pyproject_path.read_text(encoding="utf-8")
+        except OSError:
+            data = ""
+        if data:
+            try:
+                parsed = tomllib.loads(data)
+            except ValueError:
+                parsed = {}
+            version = (
+                parsed.get("project", {}).get("version")
+                if isinstance(parsed, dict)
+                else None
+            )
+            if isinstance(version, str) and version.strip():
+                return version.strip()
+
+    return "unknown"

backend/app/schemas/health.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class HealthResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    status: Literal["up", "degraded", "down"]
+    version: str
+    uptime: float
+    scanner_count: int = Field(alias="scannerCount")
+
+
+__all__ = ["HealthResponse"]