feat(oauth): wire metrics and health status for token refresh (smart-mcp-proxy#23)

Complete the OAuth token refresh reliability implementation by:
- Adding RefreshMetricsRecorder interface and wiring MetricsManager
- Recording oauth_refresh_total and oauth_refresh_duration_seconds metrics
- Wiring RefreshManager state into health calculation across all endpoints

This satisfies FR-010 (health status surfacing) and FR-011 (Prometheus metrics)
from spec 023.

Tasks completed: T014, T022, T032

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: technicalpickles

internal/oauth/refresh_manager.go

@@ -94,6 +94,16 @@ type RefreshEventEmitter interface {
 	EmitOAuthRefreshFailed(serverName string, errorMsg string)
 }
 
+// RefreshMetricsRecorder defines metrics recording methods for OAuth refresh operations.
+// This interface decouples RefreshManager from the concrete MetricsManager.
+type RefreshMetricsRecorder interface {
+	// RecordOAuthRefresh records an OAuth token refresh attempt.
+	// Result should be one of: "success", "failed_network", "failed_invalid_grant", "failed_other".
+	RecordOAuthRefresh(server, result string)
+	// RecordOAuthRefreshDuration records the duration of an OAuth token refresh attempt.
+	RecordOAuthRefreshDuration(server, result string, duration time.Duration)
+}
+
 // RefreshManagerConfig holds configuration for the RefreshManager.
 type RefreshManagerConfig struct {
 	Threshold  float64 // Percentage of lifetime at which to refresh (default: 0.8)
@@ -102,18 +112,19 @@ type RefreshManagerConfig struct {
 
 // RefreshManager coordinates proactive OAuth token refresh across all servers.
 type RefreshManager struct {
-	storage      RefreshTokenStore
-	coordinator  *OAuthFlowCoordinator
-	runtime      RefreshRuntimeOperations
-	eventEmitter RefreshEventEmitter
-	schedules    map[string]*RefreshSchedule
-	threshold    float64
-	maxRetries   int
-	mu           sync.RWMutex
-	logger       *zap.Logger
-	ctx          context.Context
-	cancel       context.CancelFunc
-	started      bool
+	storage         RefreshTokenStore
+	coordinator     *OAuthFlowCoordinator
+	runtime         RefreshRuntimeOperations
+	eventEmitter    RefreshEventEmitter
+	metricsRecorder RefreshMetricsRecorder
+	schedules       map[string]*RefreshSchedule
+	threshold       float64
+	maxRetries      int
+	mu              sync.RWMutex
+	logger          *zap.Logger
+	ctx             context.Context
+	cancel          context.CancelFunc
+	started         bool
 }
 
 // NewRefreshManager creates a new RefreshManager instance.
@@ -160,6 +171,12 @@ func (m *RefreshManager) SetEventEmitter(emitter RefreshEventEmitter) {
 	m.eventEmitter = emitter
 }
 
+// SetMetricsRecorder sets the metrics recorder for Prometheus metrics.
+// This enables FR-011: OAuth refresh metrics emission.
+func (m *RefreshManager) SetMetricsRecorder(recorder RefreshMetricsRecorder) {
+	m.metricsRecorder = recorder
+}
+
 // Start initializes the refresh manager and loads existing tokens.
 // For non-expired tokens, it schedules proactive refresh at 80% lifetime.
 // For expired tokens with valid refresh tokens, it attempts immediate refresh.
@@ -323,6 +340,13 @@ func (m *RefreshManager) executeImmediateRefresh(serverName string) {
 	// Log the result
 	LogActualTokenRefreshResult(m.logger, serverName, refreshErr == nil, duration, refreshErr)
 
+	// Record metrics (T014: Emit metrics on refresh attempt)
+	if m.metricsRecorder != nil {
+		result := classifyRefreshError(refreshErr)
+		m.metricsRecorder.RecordOAuthRefresh(serverName, result)
+		m.metricsRecorder.RecordOAuthRefreshDuration(serverName, result, duration)
+	}
+
 	if refreshErr != nil {
 		m.handleRefreshFailure(serverName, refreshErr)
 	} else {
@@ -532,13 +556,22 @@ func (m *RefreshManager) executeRefresh(serverName string) {
 	m.logger.Info("Executing proactive token refresh",
 		zap.String("server", serverName))
 
-	// Attempt refresh
+	// Attempt refresh with timing for metrics (T022: Emit refresh duration metric)
+	startTime := time.Now()
 	var refreshErr error
 	if m.runtime != nil {
 		refreshErr = m.runtime.RefreshOAuthToken(serverName)
 	} else {
 		refreshErr = ErrRefreshFailed
 	}
+	duration := time.Since(startTime)
+
+	// Record metrics (T022: Emit refresh duration metric on each attempt)
+	if m.metricsRecorder != nil {
+		result := classifyRefreshError(refreshErr)
+		m.metricsRecorder.RecordOAuthRefresh(serverName, result)
+		m.metricsRecorder.RecordOAuthRefreshDuration(serverName, result, duration)
+	}
 
 	if refreshErr != nil {
 		m.handleRefreshFailure(serverName, refreshErr)

internal/runtime/runtime.go

@@ -1473,6 +1473,20 @@ func (r *Runtime) GetManagementService() interface{} {
 	return r.managementService
 }
 
+// SetRefreshMetricsRecorder sets the metrics recorder for OAuth token refresh operations.
+// This enables FR-011: OAuth refresh metrics emission.
+func (r *Runtime) SetRefreshMetricsRecorder(recorder oauth.RefreshMetricsRecorder) {
+	if r.refreshManager != nil {
+		r.refreshManager.SetMetricsRecorder(recorder)
+	}
+}
+
+// RefreshManager returns the OAuth refresh manager for health status integration.
+// Returns nil if refresh manager hasn't been initialized.
+func (r *Runtime) RefreshManager() *oauth.RefreshManager {
+	return r.refreshManager
+}
+
 // EmitServersChanged implements the EventEmitter interface for the management service.
 // This delegates to the runtime's internal event emission mechanism.
 func (r *Runtime) EmitServersChanged(reason string, extra map[string]any) {
@@ -1699,6 +1713,16 @@ func (r *Runtime) GetAllServers() ([]map[string]interface{}, error) {
 			healthInput.TokenExpiresAt = &tokenExpiresAt
 		}
 
+		// T032: Wire refresh state into health calculation (Spec 023)
+		if r.refreshManager != nil {
+			if refreshState := r.refreshManager.GetRefreshState(serverStatus.Name); refreshState != nil {
+				healthInput.RefreshState = health.RefreshState(refreshState.State)
+				healthInput.RefreshRetryCount = refreshState.RetryCount
+				healthInput.RefreshLastError = refreshState.LastError
+				healthInput.RefreshNextAttempt = refreshState.NextAttempt
+			}
+		}
+
 		healthStatus := health.CalculateHealth(healthInput, healthConfig)
 		serverMap["health"] = healthStatus
 

internal/server/mcp.go

@@ -1802,6 +1802,19 @@ func (p *MCPProxyServer) handleListUpstreams(_ context.Context) (*mcp.CallToolRe
 			MissingSecret:  health.ExtractMissingSecret(lastError),
 			OAuthConfigErr: health.ExtractOAuthConfigError(lastError),
 		}
+
+		// T032: Wire refresh state into health calculation (Spec 023)
+		if p.mainServer != nil && p.mainServer.runtime != nil {
+			if refreshMgr := p.mainServer.runtime.RefreshManager(); refreshMgr != nil {
+				if refreshState := refreshMgr.GetRefreshState(server.Name); refreshState != nil {
+					healthInput.RefreshState = health.RefreshState(refreshState.State)
+					healthInput.RefreshRetryCount = refreshState.RetryCount
+					healthInput.RefreshLastError = refreshState.LastError
+					healthInput.RefreshNextAttempt = refreshState.NextAttempt
+				}
+			}
+		}
+
 		serverMap["health"] = health.CalculateHealth(healthInput, health.DefaultHealthConfig())
 
 		// Add Docker isolation information

internal/server/server.go

@@ -24,6 +24,7 @@ import (
 	"mcpproxy-go/internal/httpapi"
 	"mcpproxy-go/internal/logs"
 	"mcpproxy-go/internal/management"
+	"mcpproxy-go/internal/observability"
 	"mcpproxy-go/internal/runtime"
 	"mcpproxy-go/internal/secret"
 	"mcpproxy-go/internal/storage"
@@ -79,6 +80,17 @@ func NewServerWithConfigPath(cfg *config.Config, configPath string, logger *zap.
 	// This must happen before StartBackgroundInitialization is called
 	rt.SetVersion(httpapi.GetBuildVersion())
 
+	// Initialize observability manager for metrics (FR-011: OAuth refresh metrics)
+	obsConfig := observability.DefaultConfig("mcpproxy", httpapi.GetBuildVersion())
+	obsManager, err := observability.NewManager(logger.Sugar(), &obsConfig)
+	if err != nil {
+		logger.Warn("Failed to create observability manager, metrics will be disabled", zap.Error(err))
+	} else if obsManager.Metrics() != nil {
+		// Wire up metrics recorder to RefreshManager for OAuth refresh metrics
+		rt.SetRefreshMetricsRecorder(obsManager.Metrics())
+		logger.Info("OAuth refresh metrics enabled")
+	}
+
 	// Initialize management service and set it on runtime
 	secretResolver := secret.NewResolver()
 	mgmtService := management.NewService(
@@ -618,6 +630,16 @@ func (s *Server) GetAllServers() ([]map[string]interface{}, error) {
 			healthInput.OAuthRequired = true
 		}
 
+		// T032: Wire refresh state into health calculation (Spec 023)
+		if refreshMgr := s.runtime.RefreshManager(); refreshMgr != nil {
+			if refreshState := refreshMgr.GetRefreshState(serverStatus.Name); refreshState != nil {
+				healthInput.RefreshState = health.RefreshState(refreshState.State)
+				healthInput.RefreshRetryCount = refreshState.RetryCount
+				healthInput.RefreshLastError = refreshState.LastError
+				healthInput.RefreshNextAttempt = refreshState.NextAttempt
+			}
+		}
+
 		healthStatus := health.CalculateHealth(healthInput, health.DefaultHealthConfig())
 
 		result = append(result, map[string]interface{}{