health

Documentation

Overview

Package health provides unified health status calculation for upstream MCP servers.

Package health provides unified health status calculation for upstream MCP servers.

IMPORTANT: These constants are mirrored in TypeScript. When adding or modifying health levels, admin states, or actions, update cmd/generate-types/main.go and regenerate frontend/src/types/contracts.ts by running: go run ./cmd/generate-types

Index

• Constants
• func CalculateHealth(input HealthCalculatorInput, cfg *HealthCalculatorConfig) *contracts.HealthStatus
• func ExtractMissingSecret(lastError string) string
• func ExtractOAuthConfigError(lastError string) string
• func IsHealthy(health *contracts.HealthStatus, legacyConnected bool) bool
• type HealthCalculatorConfig
  • func DefaultHealthConfig() *HealthCalculatorConfig
• type HealthCalculatorInput
• type RefreshState

Constants

const (
	LevelHealthy   = "healthy"
	LevelDegraded  = "degraded"
	LevelUnhealthy = "unhealthy"
)

Health levels

const (
	StateEnabled     = "enabled"
	StateDisabled    = "disabled"
	StateQuarantined = "quarantined"
)

Admin states

const (
	ActionNone      = ""
	ActionLogin     = "login"
	ActionRestart   = "restart"
	ActionEnable    = "enable"
	ActionApprove   = "approve"
	ActionViewLogs  = "view_logs"
	ActionSetSecret = "set_secret"
	ActionConfigure = "configure"
)

Actions - suggested remediation for health issues

Functions

func CalculateHealth

func CalculateHealth(input HealthCalculatorInput, cfg *HealthCalculatorConfig) *contracts.HealthStatus

CalculateHealth calculates the unified health status for a server. The algorithm uses a priority-based approach where admin state is checked first, followed by connection state, then OAuth state.

func ExtractMissingSecret

func ExtractMissingSecret(lastError string) string

ExtractMissingSecret extracts the secret name from an error message if the error indicates a missing secret reference (e.g., unresolved environment variable). Returns the secret name or empty string if the error is not about missing secrets.

func ExtractOAuthConfigError

func ExtractOAuthConfigError(lastError string) string

ExtractOAuthConfigError extracts an OAuth configuration error from the error message. Returns the config error description or empty string if not an OAuth config issue.

func IsHealthy

func IsHealthy(health *contracts.HealthStatus, legacyConnected bool) bool

IsHealthy returns true if the server is considered healthy. It uses health.level as the source of truth, with a fallback to the legacy connected field for backward compatibility when health is nil.

Types

type HealthCalculatorConfig

type HealthCalculatorConfig struct {
	// ExpiryWarningDuration is the duration before token expiry to show degraded status.
	// Default: 1 hour
	ExpiryWarningDuration time.Duration
}

HealthCalculatorConfig contains configurable thresholds for health calculation.

func DefaultHealthConfig

func DefaultHealthConfig() *HealthCalculatorConfig

DefaultHealthConfig returns the default health calculator configuration.

type HealthCalculatorInput

type HealthCalculatorInput struct {
	// Server identification
	Name string

	// Admin state
	Enabled     bool
	Quarantined bool

	// Connection state
	State     string // "connected", "connecting", "error", "idle", "disconnected"
	Connected bool
	LastError string

	// OAuth state (only for OAuth-enabled servers)
	OAuthRequired   bool
	OAuthStatus     string     // "authenticated", "expired", "error", "none"
	TokenExpiresAt  *time.Time // When token expires
	HasRefreshToken bool       // True if refresh token exists
	UserLoggedOut   bool       // True if user explicitly logged out

	// Secret/config detection
	MissingSecret  string // Secret name if unresolved (e.g., "GITHUB_TOKEN")
	OAuthConfigErr string // OAuth config error (e.g., "requires 'resource' parameter")

	// Tool info
	ToolCount int

	// Refresh state (for health status integration - Spec 023)
	RefreshState       RefreshState // Current refresh state from RefreshManager
	RefreshRetryCount  int          // Number of retry attempts
	RefreshLastError   string       // Human-readable error message
	RefreshNextAttempt *time.Time   // When next retry will occur
}

HealthCalculatorInput contains all fields needed to calculate health status. This struct normalizes data from different sources (StateView, storage, config).

type RefreshState

type RefreshState int

RefreshState represents the current state of token refresh for health reporting. Mirrors oauth.RefreshState for decoupling.

const (
	// RefreshStateIdle means no refresh is pending or in progress.
	RefreshStateIdle RefreshState = iota
	// RefreshStateScheduled means a proactive refresh is scheduled at 80% lifetime.
	RefreshStateScheduled
	// RefreshStateRetrying means refresh failed and is retrying with exponential backoff.
	RefreshStateRetrying
	// RefreshStateFailed means refresh permanently failed (e.g., invalid_grant).
	RefreshStateFailed
)