feat(api): add operational endpoints health/readiness/version [AYG-68] (#4)

* feat(api): add operational endpoints health/readiness/version [AYG-68]

- Add /healthz, /readyz, /version root endpoints
- Add readiness Supabase check with resilient 503 response path
- Add integration tests for schemas, auth-free access, and failure paths

Fixes AYG-68

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

* fix(api): address code review findings for health endpoints [AYG-68]

- Offload sync Supabase check to thread pool via anyio.to_thread.run_sync
  to avoid blocking the async event loop (BUG-001)
- Use select("*", head=True) for lighter HEAD connectivity probe (QUAL-001)
- Add explicit AttributeError catch for missing Supabase client (QUAL-002)
- Replace str(exc) with error_type= in logger to prevent credential leak (SEC-001)
- Patch settings in test_includes_service_name and test_default_values_for_unset_env_vars
  for CI robustness (TEST-001, TEST-002)
- Strengthen test_exception_does_not_crash to assert full body values (TEST-003)

Related to AYG-68

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

---------

Co-authored-by: Aygentic <noreply@aygentic.com>

Author: amostt

backend/app/api/routes/health.py

@@ -0,0 +1,78 @@
+"""Operational endpoints: health, readiness, and version.
+
+These endpoints are public (no authentication required) and are used by
+container orchestrators for liveness/readiness probes and by API gateways
+for service registration and discovery.
+"""
+
+from __future__ import annotations
+
+import anyio
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+from postgrest.exceptions import APIError
+
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(module=__name__)
+
+router = APIRouter(tags=["operations"])
+
+
+@router.get("/healthz")
+async def healthz() -> dict[str, str]:
+    """Liveness probe — returns 200 immediately with no dependency checks."""
+    return {"status": "ok"}
+
+
+def _check_supabase(request: Request) -> str:
+    """Check Supabase connectivity via a lightweight PostgREST HEAD request.
+
+    Returns ``"ok"`` if the server is reachable (even if the probe table does
+    not exist) or ``"error"`` if the connection cannot be established.
+    """
+    try:
+        client = request.app.state.supabase
+        client.table("_health_check").select("*", head=True).execute()
+        return "ok"
+    except APIError:
+        # PostgREST returned an HTTP error (e.g. table not found).
+        # The server IS reachable — the check passes.
+        return "ok"
+    except AttributeError:
+        logger.error("supabase_client_not_initialized", check="supabase")
+        return "error"
+    except Exception as exc:
+        logger.warning(
+            "readiness_check_failed",
+            check="supabase",
+            error_type=type(exc).__name__,
+        )
+        return "error"
+
+
+@router.get("/readyz")
+async def readyz(request: Request) -> JSONResponse:
+    """Readiness probe — checks Supabase connectivity."""
+    supabase_status = await anyio.to_thread.run_sync(lambda: _check_supabase(request))
+    is_ready = supabase_status == "ok"
+    return JSONResponse(
+        status_code=200 if is_ready else 503,
+        content={
+            "status": "ready" if is_ready else "not_ready",
+            "checks": {"supabase": supabase_status},
+        },
+    )
+
+
+@router.get("/version")
+async def version() -> dict[str, str]:
+    """Build metadata from environment variables for gateway discoverability."""
+    return {
+        "service_name": settings.SERVICE_NAME,
+        "version": settings.SERVICE_VERSION,
+        "commit": settings.GIT_COMMIT,
+        "build_time": settings.BUILD_TIME,
+        "environment": settings.ENVIRONMENT,
+    }

backend/app/main.py

@@ -7,6 +7,7 @@
 from starlette.middleware.cors import CORSMiddleware
 
 from app.api.main import api_router
+from app.api.routes.health import router as health_router
 from app.core.config import settings
 from app.core.errors import register_exception_handlers
 from app.core.http_client import HttpClient
@@ -78,3 +79,6 @@ def custom_generate_unique_id(route: APIRoute) -> str:
 app.add_middleware(RequestPipelineMiddleware, environment=settings.ENVIRONMENT)
 
 app.include_router(api_router, prefix=settings.API_V1_STR)
+
+# Operational endpoints at root level (no API prefix) — public, no auth required.
+app.include_router(health_router)

backend/tests/integration/__init__.py

@@ -0,0 +1,284 @@
+"""Integration tests for operational endpoints (/healthz, /readyz, /version).
+
+Uses a minimal FastAPI app with the health router mounted. All external
+dependencies (Supabase) are mocked — no running database required.
+
+Run:
+  uv run pytest backend/tests/integration/test_health.py -v
+"""
+
+import os
+
+# Ensure required env vars are set for config.Settings import.
+# setdefault does NOT overwrite existing env vars; values below are
+# only used when running tests outside Docker (no .env loaded).
+os.environ.setdefault("SUPABASE_URL", "http://localhost:54321")
+os.environ.setdefault("SUPABASE_SERVICE_KEY", "test-service-key")
+os.environ.setdefault("CLERK_SECRET_KEY", "test-clerk-key")
+
+from unittest.mock import MagicMock, patch
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from postgrest.exceptions import APIError
+
+from app.api.routes.health import router as health_router
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_app(supabase_mock: MagicMock | None = None) -> FastAPI:
+    """Create a minimal FastAPI app with the health router."""
+    app = FastAPI()
+    app.include_router(health_router)
+    if supabase_mock is not None:
+        app.state.supabase = supabase_mock
+    return app
+
+
+def _healthy_supabase() -> MagicMock:
+    """Return a mock Supabase client that reports healthy."""
+    mock = MagicMock()
+    mock.table.return_value.select.return_value.execute.return_value = MagicMock()
+    return mock
+
+
+def _unreachable_supabase() -> MagicMock:
+    """Return a mock Supabase client that simulates connection failure."""
+    mock = MagicMock()
+    mock.table.side_effect = ConnectionError("Connection refused")
+    return mock
+
+
+def _api_error_supabase() -> MagicMock:
+    """Return a mock Supabase client where table doesn't exist (PostgREST APIError).
+
+    This simulates the table not existing, but the server being reachable.
+    """
+    mock = MagicMock()
+    mock.table.return_value.select.return_value.execute.side_effect = APIError(
+        {"message": "relation '_health_check' does not exist", "code": "PGRST204"}
+    )
+    return mock
+
+
+# ---------------------------------------------------------------------------
+# /healthz — Liveness probe
+# ---------------------------------------------------------------------------
+
+
+class TestHealthz:
+    """Liveness probe tests."""
+
+    def test_returns_200_ok(self) -> None:
+        """GET /healthz returns 200 with {"status": "ok"}."""
+        client = TestClient(_make_app())
+
+        response = client.get("/healthz")
+
+        assert response.status_code == 200
+        assert response.json() == {"status": "ok"}
+
+    def test_no_auth_required(self) -> None:
+        """GET /healthz succeeds without Authorization header."""
+        client = TestClient(_make_app())
+
+        response = client.get("/healthz", headers={})
+
+        assert response.status_code == 200
+
+    def test_response_schema_exact(self) -> None:
+        """Response contains only the 'status' field — no extra keys."""
+        client = TestClient(_make_app())
+
+        data = client.get("/healthz").json()
+
+        assert set(data.keys()) == {"status"}
+
+    def test_never_checks_dependencies(self) -> None:
+        """Healthz does not access app.state.supabase (liveness only)."""
+        mock = MagicMock()
+        client = TestClient(_make_app(supabase_mock=mock))
+
+        client.get("/healthz")
+
+        mock.table.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# /readyz — Readiness probe
+# ---------------------------------------------------------------------------
+
+
+class TestReadyz:
+    """Readiness probe tests."""
+
+    def test_healthy_supabase_returns_200(self) -> None:
+        """GET /readyz returns 200 when Supabase is reachable."""
+        client = TestClient(_make_app(supabase_mock=_healthy_supabase()))
+
+        response = client.get("/readyz")
+
+        assert response.status_code == 200
+        assert response.json() == {
+            "status": "ready",
+            "checks": {"supabase": "ok"},
+        }
+
+    def test_unreachable_supabase_returns_503(self) -> None:
+        """GET /readyz returns 503 when Supabase is unreachable."""
+        client = TestClient(_make_app(supabase_mock=_unreachable_supabase()))
+
+        response = client.get("/readyz")
+
+        assert response.status_code == 503
+        assert response.json() == {
+            "status": "not_ready",
+            "checks": {"supabase": "error"},
+        }
+
+    def test_api_error_still_reports_ok(self) -> None:
+        """PostgREST APIError (table not found) means server IS reachable."""
+        client = TestClient(_make_app(supabase_mock=_api_error_supabase()))
+
+        response = client.get("/readyz")
+
+        assert response.status_code == 200
+        assert response.json()["checks"]["supabase"] == "ok"
+
+    def test_missing_supabase_client_returns_503(self) -> None:
+        """GET /readyz returns 503 when app.state.supabase is not set."""
+        client = TestClient(_make_app())  # No supabase mock set
+
+        response = client.get("/readyz")
+
+        assert response.status_code == 503
+        assert response.json()["checks"]["supabase"] == "error"
+
+    def test_exception_does_not_crash(self) -> None:
+        """Supabase check exception returns valid JSON, not a 500 crash."""
+        mock = MagicMock()
+        mock.table.side_effect = RuntimeError("unexpected")
+        client = TestClient(_make_app(supabase_mock=mock))
+
+        response = client.get("/readyz")
+
+        assert response.status_code == 503
+        assert response.headers["content-type"] == "application/json"
+        body = response.json()
+        assert body["status"] == "not_ready"
+        assert body["checks"]["supabase"] == "error"
+
+    def test_no_auth_required(self) -> None:
+        """GET /readyz succeeds without Authorization header."""
+        client = TestClient(_make_app(supabase_mock=_healthy_supabase()))
+
+        response = client.get("/readyz", headers={})
+
+        assert response.status_code == 200
+
+    def test_response_schema_exact(self) -> None:
+        """Response contains only 'status' and 'checks' — no extra keys."""
+        client = TestClient(_make_app(supabase_mock=_healthy_supabase()))
+
+        data = client.get("/readyz").json()
+
+        assert set(data.keys()) == {"status", "checks"}
+        assert set(data["checks"].keys()) == {"supabase"}
+
+
+# ---------------------------------------------------------------------------
+# /version — Build metadata
+# ---------------------------------------------------------------------------
+
+
+class TestVersion:
+    """Build metadata endpoint tests."""
+
+    def test_returns_200_with_metadata(self) -> None:
+        """GET /version returns 200 with all required metadata fields."""
+        client = TestClient(_make_app())
+
+        response = client.get("/version")
+
+        assert response.status_code == 200
+        data = response.json()
+        assert "service_name" in data
+        assert "version" in data
+        assert "commit" in data
+        assert "build_time" in data
+        assert "environment" in data
+
+    def test_includes_service_name(self) -> None:
+        """GET /version includes service_name for gateway discoverability."""
+        mock_settings = MagicMock()
+        mock_settings.SERVICE_NAME = "my-service"
+        mock_settings.SERVICE_VERSION = "0.1.0"
+        mock_settings.GIT_COMMIT = "unknown"
+        mock_settings.BUILD_TIME = "unknown"
+        mock_settings.ENVIRONMENT = "local"
+
+        with patch("app.api.routes.health.settings", mock_settings):
+            data = TestClient(_make_app()).get("/version").json()
+
+        assert data["service_name"] == "my-service"
+
+    def test_default_values_for_unset_env_vars(self) -> None:
+        """GIT_COMMIT and BUILD_TIME default to 'unknown' when not set."""
+        mock_settings = MagicMock()
+        mock_settings.SERVICE_NAME = "my-service"
+        mock_settings.SERVICE_VERSION = "0.1.0"
+        mock_settings.GIT_COMMIT = "unknown"
+        mock_settings.BUILD_TIME = "unknown"
+        mock_settings.ENVIRONMENT = "local"
+
+        with patch("app.api.routes.health.settings", mock_settings):
+            data = TestClient(_make_app()).get("/version").json()
+
+        assert data["commit"] == "unknown"
+        assert data["build_time"] == "unknown"
+
+    def test_custom_settings_values(self) -> None:
+        """Version endpoint reflects custom settings values."""
+        mock_settings = MagicMock()
+        mock_settings.SERVICE_NAME = "custom-service"
+        mock_settings.SERVICE_VERSION = "2.0.0"
+        mock_settings.GIT_COMMIT = "abc1234"
+        mock_settings.BUILD_TIME = "2026-02-28T00:00:00Z"
+        mock_settings.ENVIRONMENT = "staging"
+
+        with patch("app.api.routes.health.settings", mock_settings):
+            client = TestClient(_make_app())
+            data = client.get("/version").json()
+
+        assert data == {
+            "service_name": "custom-service",
+            "version": "2.0.0",
+            "commit": "abc1234",
+            "build_time": "2026-02-28T00:00:00Z",
+            "environment": "staging",
+        }
+
+    def test_response_schema_exact(self) -> None:
+        """Response contains exactly the five expected fields."""
+        client = TestClient(_make_app())
+
+        data = client.get("/version").json()
+
+        assert set(data.keys()) == {
+            "service_name",
+            "version",
+            "commit",
+            "build_time",
+            "environment",
+        }
+
+    def test_no_auth_required(self) -> None:
+        """GET /version succeeds without Authorization header."""
+        client = TestClient(_make_app())
+
+        response = client.get("/version", headers={})
+
+        assert response.status_code == 200