Documentation
¶
Overview ¶
Package healthcheck provides common healthcheck functionality for ToolHive proxies. It includes MCP server status information and standardized response formats.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HealthChecker ¶
type HealthChecker struct {
// contains filtered or unexported fields
}
HealthChecker provides health check functionality for proxies
func NewHealthChecker ¶
func NewHealthChecker(transport string, mcpPinger MCPPinger, opts ...Option) *HealthChecker
NewHealthChecker creates a new health checker instance
func (*HealthChecker) CheckHealth ¶
func (hc *HealthChecker) CheckHealth(ctx context.Context) *HealthResponse
CheckHealth performs a comprehensive health check including MCP server status. With WithLastResult, it also records a copy of the response for ServeHTTP.
func (*HealthChecker) ServeHTTP ¶
func (hc *HealthChecker) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler for health check endpoints
type HealthResponse ¶
type HealthResponse struct {
// Status is the overall health status
Status HealthStatus `json:"status"`
// Timestamp is when the health check was performed
Timestamp time.Time `json:"timestamp"`
// Transport indicates the type of transport used by the MCP server (stdio, sse)
Transport string `json:"transport"`
// MCP contains MCP server status information
MCP *MCPStatus `json:"mcp,omitempty"`
}
HealthResponse represents the standardized health check response.
This endpoint is unauthenticated (it must stay reachable for Kubernetes liveness and readiness probes), so it deliberately exposes no build fingerprint — version, commit, build date, Go version, or platform. This matches the minimal shape already used by the vMCP server and the v1 API, which redact the same information to avoid disclosure on an unauthenticated path.
type HealthStatus ¶
type HealthStatus string
HealthStatus represents the overall health status
const ( // StatusHealthy indicates the service is healthy StatusHealthy HealthStatus = "healthy" // StatusUnhealthy indicates the service is unhealthy StatusUnhealthy HealthStatus = "unhealthy" // StatusDegraded indicates the service is partially healthy StatusDegraded HealthStatus = "degraded" )
type MCPPinger ¶
type MCPPinger interface {
// Ping sends a ping request to the MCP server and returns the response time
// The implementation should send a JSON-RPC request with method "ping" and no parameters,
// and expect an empty response: {"jsonrpc": "2.0", "id": "123", "result": {}}
Ping(ctx context.Context) (time.Duration, error)
}
MCPPinger defines the interface for pinging MCP servers Implementations should follow the MCP ping specification: https://modelcontextprotocol.io/specification/2025-03-26/basic/utilities/ping
type MCPStatus ¶
type MCPStatus struct {
// Available indicates if the MCP server is reachable
Available bool `json:"available"`
// ResponseTime is the time taken to ping the MCP server (in milliseconds)
ResponseTime *int64 `json:"response_time_ms,omitempty"`
// Error contains any error message if the MCP server is not available
Error string `json:"error,omitempty"`
// LastChecked is the timestamp of the last health check
LastChecked time.Time `json:"last_checked"`
}
MCPStatus represents the status of an MCP server connection
type Option ¶ added in v0.60.0
type Option func(*HealthChecker)
Option configures a HealthChecker.
func WithLastResult ¶ added in v0.60.0
func WithLastResult() Option
WithLastResult makes ServeHTTP answer from the result of the most recent CheckHealth call instead of pinging the MCP server for every request, so a slow MCP server cannot hold the answer past a caller's timeout, such as a Kubernetes probe's. The answer is only as fresh as the caller keeps it: the caller must run CheckHealth on its own schedule. Until the first CheckHealth call returns, ServeHTTP reports the proxy's own status without MCP details.
Source Files