parent fb475a8

author taskbot <taskbot@users.noreply.github.com> 1766072123 +0100
committer taskbot <taskbot@users.noreply.github.com> 1766158585 +0100

Integrate health monitoring into vMCP server

Integrates the health monitoring infrastructure (from previous into
the vMCP server, enabling periodic backend health checks with configurable
Related-to: #3036

  intervals and thresholds.

changes from review

changes from review

add missing method

Apply suggestion from @Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: taskbot

cmd/vmcp/app/commands.go

@@ -20,6 +20,7 @@ import (
 	vmcpclient "github.com/stacklok/toolhive/pkg/vmcp/client"
 	"github.com/stacklok/toolhive/pkg/vmcp/config"
 	"github.com/stacklok/toolhive/pkg/vmcp/discovery"
+	"github.com/stacklok/toolhive/pkg/vmcp/health"
 	vmcprouter "github.com/stacklok/toolhive/pkg/vmcp/router"
 	vmcpserver "github.com/stacklok/toolhive/pkg/vmcp/server"
 )
@@ -253,6 +254,8 @@ func discoverBackends(ctx context.Context, cfg *config.Config) ([]vmcp.Backend,
 }
 
 // runServe implements the serve command logic
+//
+//nolint:gocyclo // Complexity from server initialization and configuration is acceptable
 func runServe(cmd *cobra.Command, _ []string) error {
 	ctx := cmd.Context()
 	configPath := viper.GetString("config")
@@ -330,15 +333,29 @@ func runServe(cmd *cobra.Command, _ []string) error {
 		}()
 	}
 
+	// Configure health monitoring if enabled
+	var healthMonitorConfig *health.MonitorConfig
+	if cfg.Operational != nil && cfg.Operational.FailureHandling != nil && cfg.Operational.FailureHandling.HealthCheckInterval > 0 {
+		defaults := health.DefaultConfig()
+		healthMonitorConfig = &health.MonitorConfig{
+			CheckInterval:      time.Duration(cfg.Operational.FailureHandling.HealthCheckInterval),
+			UnhealthyThreshold: cfg.Operational.FailureHandling.UnhealthyThreshold,
+			Timeout:            defaults.Timeout,
+			DegradedThreshold:  defaults.DegradedThreshold,
+		}
+		logger.Info("Health monitoring configured from operational settings")
+	}
+
 	serverCfg := &vmcpserver.Config{
-		Name:              cfg.Name,
-		Version:           getVersion(),
-		Host:              host,
-		Port:              port,
-		AuthMiddleware:    authMiddleware,
-		AuthInfoHandler:   authInfoHandler,
-		TelemetryProvider: telemetryProvider,
-		AuditConfig:       cfg.Audit,
+		Name:                cfg.Name,
+		Version:             getVersion(),
+		Host:                host,
+		Port:                port,
+		AuthMiddleware:      authMiddleware,
+		AuthInfoHandler:     authInfoHandler,
+		TelemetryProvider:   telemetryProvider,
+		AuditConfig:         cfg.Audit,
+		HealthMonitorConfig: healthMonitorConfig,
 	}
 
 	// Convert composite tool configurations to workflow definitions

pkg/vmcp/auth/strategies/header_injection.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/stacklok/toolhive/pkg/validation"
 	authtypes "github.com/stacklok/toolhive/pkg/vmcp/auth/types"
+	"github.com/stacklok/toolhive/pkg/vmcp/health"
 )
 
 // HeaderInjectionStrategy injects a static header value into request headers.
@@ -46,20 +47,26 @@ func (*HeaderInjectionStrategy) Name() string {
 // Authenticate injects the header value from the strategy config into the request header.
 //
 // This method:
-//  1. Validates that HeaderName and HeaderValue are present in the strategy config
-//  2. Sets the specified header with the provided value
+//  1. Skips authentication if this is a health check request
+//  2. Validates that HeaderName and HeaderValue are present in the strategy config
+//  3. Sets the specified header with the provided value
 //
 // Parameters:
-//   - ctx: Request context (currently unused, reserved for future secret resolution)
+//   - ctx: Request context (used to check for health check marker)
 //   - req: The HTTP request to authenticate
 //   - strategy: The backend auth strategy configuration containing HeaderInjection
 //
 // Returns an error if:
 //   - HeaderName is missing or empty
 //   - HeaderValue is missing or empty
 func (*HeaderInjectionStrategy) Authenticate(
-	_ context.Context, req *http.Request, strategy *authtypes.BackendAuthStrategy,
+	ctx context.Context, req *http.Request, strategy *authtypes.BackendAuthStrategy,
 ) error {
+	// Skip authentication for health checks
+	if health.IsHealthCheck(ctx) {
+		return nil
+	}
+
 	if strategy == nil || strategy.HeaderInjection == nil {
 		return fmt.Errorf("header_injection configuration required")
 	}

pkg/vmcp/auth/strategies/tokenexchange.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/auth/tokenexchange"
 	"github.com/stacklok/toolhive/pkg/env"
 	authtypes "github.com/stacklok/toolhive/pkg/vmcp/auth/types"
+	"github.com/stacklok/toolhive/pkg/vmcp/health"
 )
 
 const (
@@ -69,18 +70,19 @@ func (*TokenExchangeStrategy) Name() string {
 // Authenticate exchanges the client's token for a backend token and injects it.
 //
 // This method:
-//  1. Retrieves the client's identity and token from the context
-//  2. Parses and validates the token exchange configuration from strategy
-//  3. Gets or creates a cached ExchangeConfig for this backend configuration
-//  4. Creates a TokenSource with the current identity token
-//  5. Obtains an access token by performing the exchange
-//  6. Injects the token into the backend request's Authorization header
+//  1. Skips authentication if this is a health check request
+//  2. Retrieves the client's identity and token from the context
+//  3. Parses and validates the token exchange configuration from strategy
+//  4. Gets or creates a cached ExchangeConfig for this backend configuration
+//  5. Creates a TokenSource with the current identity token
+//  6. Obtains an access token by performing the exchange
+//  7. Injects the token into the backend request's Authorization header
 //
 // Token caching per user is handled by the upper vMCP TokenCache layer.
 // This strategy only caches the ExchangeConfig template per backend.
 //
 // Parameters:
-//   - ctx: Request context containing the authenticated identity
+//   - ctx: Request context containing the authenticated identity (or health check marker)
 //   - req: The HTTP request to authenticate
 //   - strategy: Backend auth strategy containing token exchange configuration
 //
@@ -92,6 +94,11 @@ func (*TokenExchangeStrategy) Name() string {
 func (s *TokenExchangeStrategy) Authenticate(
 	ctx context.Context, req *http.Request, strategy *authtypes.BackendAuthStrategy,
 ) error {
+	// Skip authentication for health checks
+	if health.IsHealthCheck(ctx) {
+		return nil
+	}
+
 	identity, ok := auth.IdentityFromContext(ctx)
 	if !ok {
 		return fmt.Errorf("no identity found in context")

pkg/vmcp/health/monitor.go

@@ -10,6 +10,24 @@ import (
 	"github.com/stacklok/toolhive/pkg/vmcp"
 )
 
+// healthCheckContextKey is a marker for health check requests.
+type healthCheckContextKey struct{}
+
+// WithHealthCheckMarker marks a context as a health check request.
+// Authentication layers can use IsHealthCheck to identify and skip authentication
+// for health check requests.
+func WithHealthCheckMarker(ctx context.Context) context.Context {
+	return context.WithValue(ctx, healthCheckContextKey{}, true)
+}
+
+// IsHealthCheck returns true if the context is marked as a health check.
+// Authentication strategies use this to bypass authentication for health checks,
+// since health checks verify backend availability and should not require user credentials.
+func IsHealthCheck(ctx context.Context) bool {
+	val, ok := ctx.Value(healthCheckContextKey{}).(bool)
+	return ok && val
+}
+
 // Monitor performs periodic health checks on backend MCP servers.
 // It runs background goroutines for each backend, tracking their health status
 // and consecutive failure counts. The monitor supports graceful shutdown and
@@ -219,8 +237,12 @@ func (m *Monitor) performHealthCheck(ctx context.Context, backend *vmcp.Backend)
 		Metadata:      backend.Metadata,
 	}
 
+	// Mark context as health check to bypass authentication
+	// Health checks verify backend availability and should not require user credentials
+	healthCheckCtx := WithHealthCheckMarker(ctx)
+
 	// Perform health check
-	status, err := m.checker.CheckHealth(ctx, target)
+	status, err := m.checker.CheckHealth(healthCheckCtx, target)
 
 	// Record result in status tracker
 	if err != nil {