Skip to content

ccproxy.api.routes.health

ccproxy.api.routes.health

Health check endpoints for CCProxy API Server.

Implements modern health check patterns following 2024 best practices: - /health/live: Liveness probe for Kubernetes (minimal, fast) - /health/ready: Readiness probe for Kubernetes (critical dependencies) - /health: Detailed diagnostics (comprehensive status)

Follows IETF Health Check Response Format draft standard.

liveness_probe async 

liveness_probe(response)

Liveness probe for Kubernetes.

Minimal health check that only verifies the application process is running. Used by Kubernetes to determine if the pod should be restarted.

Returns:

Type Description
dict[str, Any]

Simple health status following IETF health check format
Source code in ccproxy/api/routes/health.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@router.get(
    "/health/live",
    response_class=HealthJSONResponse,
    responses=_health_responses("Liveness probe result"),
)
async def liveness_probe(response: Response) -> dict[str, Any]:
    """Liveness probe for Kubernetes.

    Minimal health check that only verifies the application process is running.
    Used by Kubernetes to determine if the pod should be restarted.

    Returns:
        Simple health status following IETF health check format
    """
    response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
    response.headers["Content-Type"] = "application/health+json"

    logger.debug("liveness_probe_request")

    return {
        "status": "pass",
        "version": __version__,
        "output": "Application process is running",
    }

readiness_probe async 

readiness_probe(response)

Readiness probe for Kubernetes.

Checks critical dependencies to determine if the service is ready to accept traffic. Used by Kubernetes to determine if the pod should receive traffic.

Returns:

Type Description
dict[str, Any]

Readiness status with critical dependency checks
Source code in ccproxy/api/routes/health.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
@router.get(
    "/health/ready",
    response_class=HealthJSONResponse,
    responses=_health_responses("Readiness probe result"),
)
async def readiness_probe(response: Response) -> dict[str, Any]:
    """Readiness probe for Kubernetes.

    Checks critical dependencies to determine if the service is ready to accept traffic.
    Used by Kubernetes to determine if the pod should receive traffic.

    Returns:
        Readiness status with critical dependency checks
    """
    response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
    response.headers["Content-Type"] = "application/health+json"

    logger.debug("readiness_probe_request")

    # Core readiness only checks application availability; plugins provide their own health
    return {
        "status": "pass",
        "version": __version__,
        "output": "Service is ready to accept traffic",
    }

detailed_health_check async 

detailed_health_check(response)

Comprehensive health check for diagnostics and monitoring.

Provides detailed status of core service only. Provider/plugin-specific health, including CLI availability, is reported by each plugin's health endpoint.

Returns:

Type Description
dict[str, Any]

Detailed health status following IETF health check format
Source code in ccproxy/api/routes/health.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
@router.get(
    "/health",
    response_class=HealthJSONResponse,
    responses=_health_responses("Detailed health diagnostics"),
)
async def detailed_health_check(response: Response) -> dict[str, Any]:
    """Comprehensive health check for diagnostics and monitoring.

    Provides detailed status of core service only. Provider/plugin-specific
    health, including CLI availability, is reported by each plugin's health endpoint.

    Returns:
        Detailed health status following IETF health check format
    """
    response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
    response.headers["Content-Type"] = "application/health+json"

    logger.debug("detailed_health_check_request")

    overall_status = "pass"
    response.status_code = status.HTTP_200_OK

    current_time = datetime.now(UTC).isoformat()

    return {
        "status": overall_status,
        "version": __version__,
        "serviceId": "claude-code-proxy",
        "description": "CCProxy API Server",
        "time": current_time,
        "checks": {
            "service_container": [
                {
                    "componentId": "service-container",
                    "componentType": "service",
                    "status": "pass",
                    "time": current_time,
                    "output": "Service container operational",
                    "version": __version__,
                }
            ],
        },
    }