Merge pull request #198 from AAdewunmi/feat/add-readiness-endpoint

Feat/add readiness endpoint

Author: AAdewunmi

config/urls.py

@@ -23,6 +23,7 @@
     ),
     path("ops/", include(("returns.urls.ops", "ops"), namespace="ops")),
     path("console/", include("console.urls")),
+    path("api/", include("core.api.urls")),
     path("api/analytics/", include("analytics.api.urls")),
     path("api/returns/", include("returns.api.urls")),
     path("admin/", admin.site.urls),

core/api/urls.py

@@ -0,0 +1,13 @@
+"""URL routes for core operational API endpoints."""
+
+from __future__ import annotations
+
+from django.urls import path
+
+from core.api.views import HealthCheckView
+
+app_name = "core_api"
+
+urlpatterns = [
+    path("health/", HealthCheckView.as_view(), name="health"),
+]

core/api/views.py

@@ -0,0 +1,25 @@
+"""Operational API views for ReturnHub core endpoints."""
+
+from __future__ import annotations
+
+from rest_framework import status
+from rest_framework.permissions import AllowAny
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from core.health import get_readiness_payload
+
+
+class HealthCheckView(APIView):
+    """Expose a small readiness contract for load balancers and probes."""
+
+    authentication_classes: list[type] = []
+    permission_classes = [AllowAny]
+
+    def get(self, request, *args, **kwargs) -> Response:
+        """Return the current readiness state for the application."""
+        payload = get_readiness_payload()
+        response_status = (
+            status.HTTP_200_OK if payload["status"] == "ok" else status.HTTP_503_SERVICE_UNAVAILABLE
+        )
+        return Response(payload, status=response_status)

core/health.py

@@ -0,0 +1,49 @@
+"""Health and readiness checks used by deployment and monitoring tooling."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.conf import settings
+from django.db import connections
+from django.db.utils import OperationalError
+from django.utils import timezone
+
+
+def check_database() -> tuple[bool, str]:
+    """Return whether the default database is reachable.
+
+    The readiness check uses a lightweight ``SELECT 1`` probe so the endpoint
+    verifies the actual connection path that the application depends on in
+    production. The text message is intentionally stable because external
+    tooling may display or log it directly.
+    """
+    try:
+        with connections["default"].cursor() as cursor:
+            cursor.execute("SELECT 1")
+            cursor.fetchone()
+    except OperationalError:
+        return False, "unavailable"
+
+    return True, "ok"
+
+
+def get_readiness_payload() -> dict[str, Any]:
+    """Build the stable readiness payload returned by ``/api/health/``.
+
+    Returns:
+        A serialisable dictionary containing the service status, a release
+        identifier, a UTC timestamp, and named dependency checks.
+    """
+    database_ok, database_status = check_database()
+    overall_status = "ok" if database_ok else "degraded"
+
+    return {
+        "status": overall_status,
+        "service": "returnhub",
+        "release": getattr(settings, "RELEASE_VERSION", "dev"),
+        "timestamp": timezone.now().isoformat(),
+        "checks": {
+            "database": database_status,
+        },
+    }

docs/sprint-runbook/sprint-6/sprint-6-multi-surface-verification.md

@@ -3,6 +3,14 @@
 
 This runbook verifies the current ReturnHub multi-surface experience using the live repository structure. It covers seeded demo access, public entry points, role-specific console routes, paginated surface routes, wrong-role handling, and the smoke tests that back those flows in the test suite.
 
+For an executable version of this runbook, use:
+
+```bash
+./docs/sprint-runbook/sprint-6/sprint-6-multi-surface-verification.sh
+```
+
+The shell runbooks are written to fail with compact `CHECK_FAILED=` or `UNEXPECTED_ERROR=` lines instead of printing full Python tracebacks.
+
 ## Scope
 
 This document is aligned to the current project state:
@@ -36,7 +44,9 @@ Expected result:
 
 - `web` is running
 - the seed command reports `ReturnHub demo seed complete.`
-- the seed command prints the seeded usernames and a total case count of `32`
+- the seed command prints the seeded usernames
+- the seed command prints `Seeded demo subset count: 32`
+- the seed command may print a larger live `Total cases` value in non-pristine local databases
 
 ## Seeded Users
 

tests/test_core_health_api.py

@@ -0,0 +1,139 @@
+"""Tests for core health helpers and readiness API views."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from django.db.utils import OperationalError
+from rest_framework import status
+from rest_framework.test import APIRequestFactory
+
+from core.api.views import HealthCheckView
+from core.health import check_database, get_readiness_payload
+
+
+class _HealthyCursor:
+    """Minimal cursor stub for the successful database probe path."""
+
+    def __init__(self) -> None:
+        self.executed_sql: list[str] = []
+        self.fetchone_calls = 0
+
+    def __enter__(self) -> _HealthyCursor:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        return None
+
+    def execute(self, sql: str) -> None:
+        self.executed_sql.append(sql)
+
+    def fetchone(self) -> tuple[int]:
+        self.fetchone_calls += 1
+        return (1,)
+
+
+class _HealthyConnection:
+    """Connection stub that returns the supplied cursor."""
+
+    def __init__(self, cursor: _HealthyCursor) -> None:
+        self._cursor = cursor
+
+    def cursor(self) -> _HealthyCursor:
+        return self._cursor
+
+
+class _UnavailableConnection:
+    """Connection stub that raises the expected operational error."""
+
+    def cursor(self):
+        raise OperationalError("database unavailable")
+
+
+def test_check_database_returns_ok_when_default_database_is_reachable(monkeypatch) -> None:
+    """The probe should execute a lightweight query and report success."""
+
+    cursor = _HealthyCursor()
+    monkeypatch.setattr(
+        "core.health.connections",
+        {"default": _HealthyConnection(cursor)},
+    )
+
+    assert check_database() == (True, "ok")
+    assert cursor.executed_sql == ["SELECT 1"]
+    assert cursor.fetchone_calls == 1
+
+
+def test_check_database_returns_unavailable_on_operational_error(monkeypatch) -> None:
+    """Operational errors should degrade the readiness dependency check."""
+
+    monkeypatch.setattr(
+        "core.health.connections",
+        {"default": _UnavailableConnection()},
+    )
+
+    assert check_database() == (False, "unavailable")
+
+
+def test_get_readiness_payload_includes_release_timestamp_and_checks(monkeypatch, settings) -> None:
+    """The readiness payload should expose the stable response contract."""
+
+    fixed_now = datetime(2026, 4, 21, 9, 3, 36, tzinfo=UTC)
+    monkeypatch.setattr("core.health.check_database", lambda: (True, "ok"))
+    monkeypatch.setattr("core.health.timezone.now", lambda: fixed_now)
+    settings.RELEASE_VERSION = "2026.04.21"
+
+    assert get_readiness_payload() == {
+        "status": "ok",
+        "service": "returnhub",
+        "release": "2026.04.21",
+        "timestamp": fixed_now.isoformat(),
+        "checks": {"database": "ok"},
+    }
+
+
+def test_get_readiness_payload_falls_back_to_degraded_and_dev_release(
+    monkeypatch, settings
+) -> None:
+    """The helper should preserve safe defaults for degraded environments."""
+
+    fixed_now = datetime(2026, 4, 21, 9, 3, 36, tzinfo=UTC)
+    monkeypatch.setattr("core.health.check_database", lambda: (False, "unavailable"))
+    monkeypatch.setattr("core.health.timezone.now", lambda: fixed_now)
+    del settings.RELEASE_VERSION
+
+    assert get_readiness_payload() == {
+        "status": "degraded",
+        "service": "returnhub",
+        "release": "dev",
+        "timestamp": fixed_now.isoformat(),
+        "checks": {"database": "unavailable"},
+    }
+
+
+def test_health_check_view_returns_200_for_healthy_payload(monkeypatch) -> None:
+    """The API view should return 200 when the app is ready."""
+
+    monkeypatch.setattr(
+        "core.api.views.get_readiness_payload",
+        lambda: {"status": "ok", "checks": {"database": "ok"}},
+    )
+
+    response = HealthCheckView.as_view()(APIRequestFactory().get("/api/health/"))
+
+    assert response.status_code == status.HTTP_200_OK
+    assert response.data == {"status": "ok", "checks": {"database": "ok"}}
+
+
+def test_health_check_view_returns_503_for_degraded_payload(monkeypatch) -> None:
+    """The API view should signal unready status to probes and load balancers."""
+
+    monkeypatch.setattr(
+        "core.api.views.get_readiness_payload",
+        lambda: {"status": "degraded", "checks": {"database": "unavailable"}},
+    )
+
+    response = HealthCheckView.as_view()(APIRequestFactory().get("/api/health/"))
+
+    assert response.status_code == status.HTTP_503_SERVICE_UNAVAILABLE
+    assert response.data == {"status": "degraded", "checks": {"database": "unavailable"}}

tests/test_core_urls.py

@@ -30,6 +30,13 @@ def test_ops_namespace_routes_to_real_case_detail_page() -> None:
     assert resolve("/ops/42/").view_name == "ops:case-detail"
 
 
+def test_api_health_route_resolves_to_core_health_check() -> None:
+    """The root router should expose the operational health endpoint."""
+
+    assert reverse("core_api:health") == "/api/health/"
+    assert resolve("/api/health/").view_name == "core_api:health"
+
+
 def test_config_urls_appends_media_patterns_when_debug(monkeypatch) -> None:
     """Root URLs should append media-serving patterns in debug mode."""