management

Documentation

Overview

Package management provides unified server lifecycle and diagnostic operations. It consolidates duplicate logic from CLI, REST, and MCP interfaces into a single service layer.

Index

• type BulkOperationResult
• type EventEmitter
• type RuntimeOperations
• type Service
  • func NewService(runtime RuntimeOperations, cfg *config.Config, eventEmitter EventEmitter, ...) Service

Types

type BulkOperationResult

type BulkOperationResult struct {
	Total      int               `json:"total"`      // Total servers processed
	Successful int               `json:"successful"` // Number of successful operations
	Failed     int               `json:"failed"`     // Number of failed operations
	Errors     map[string]string `json:"errors"`     // Map of server name to error message
}

BulkOperationResult holds the results of a bulk operation across multiple servers.

type EventEmitter

type EventEmitter interface {
	EmitServersChanged(reason string, extra map[string]any)
}

EventEmitter defines the interface for emitting runtime events. This is used by the service to notify subscribers of state changes.

type RuntimeOperations

type RuntimeOperations interface {
	EnableServer(serverName string, enabled bool) error
	RestartServer(serverName string) error
	GetAllServers() ([]map[string]interface{}, error)
	BulkEnableServers(serverNames []string, enabled bool) (map[string]error, error)
	GetServerTools(serverName string) ([]map[string]interface{}, error)
	TriggerOAuthLogin(serverName string) error
	// TriggerOAuthLoginQuick returns browser status immediately (Spec 020 fix)
	TriggerOAuthLoginQuick(serverName string) (*core.OAuthStartResult, error)
	TriggerOAuthLogout(serverName string) error
	RefreshOAuthToken(serverName string) error
}

RuntimeOperations defines the interface for runtime operations needed by the service. This allows the service to delegate to runtime without a direct dependency.

type Service

type Service interface {

	// ListServers returns all configured servers with their current status and aggregate statistics.
	// This method respects configuration gates but never blocks read operations.
	ListServers(ctx context.Context) ([]*contracts.Server, *contracts.ServerStats, error)

	// GetServerLogs retrieves recent log entries for a specific server.
	// The tail parameter controls how many recent entries to return.
	// Returns empty slice if server doesn't exist or has no logs.
	GetServerLogs(ctx context.Context, name string, tail int) ([]contracts.LogEntry, error)

	// EnableServer enables or disables a specific upstream server.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful state change.
	EnableServer(ctx context.Context, name string, enabled bool) error

	// RestartServer stops and restarts the connection to a specific upstream server.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful restart.
	RestartServer(ctx context.Context, name string) error

	// RestartAll restarts all configured servers sequentially.
	// Returns detailed results including success/failure counts and per-server errors.
	// Continues on partial failures, collecting all errors in the result.
	// This operation respects disable_management and read_only configuration gates.
	RestartAll(ctx context.Context) (*BulkOperationResult, error)

	// EnableAll enables all configured servers.
	// Returns detailed results including success/failure counts and per-server errors.
	// This operation respects disable_management and read_only configuration gates.
	EnableAll(ctx context.Context) (*BulkOperationResult, error)

	// DisableAll disables all configured servers.
	// Returns detailed results including success/failure counts and per-server errors.
	// This operation respects disable_management and read_only configuration gates.
	DisableAll(ctx context.Context) (*BulkOperationResult, error)

	// Doctor aggregates health diagnostics from all system components.
	// Returns comprehensive health information including:
	// - Upstream server connection errors
	// - OAuth authentication requirements
	// - Missing secrets referenced in configuration
	// - Docker daemon status (if isolation is enabled)
	// - General runtime warnings
	// Target completion time: <3 seconds for 20 servers.
	Doctor(ctx context.Context) (*contracts.Diagnostics, error)

	// AuthStatus returns detailed OAuth authentication status for a specific server.
	// Returns nil if server doesn't use OAuth or doesn't exist.
	AuthStatus(ctx context.Context, name string) (*contracts.AuthStatus, error)

	// GetServerTools retrieves all available tools for a specific upstream MCP server.
	// Delegates to runtime's GetServerTools() which reads from StateView cache.
	// This is a read-only operation that completes in <10ms (in-memory cache read).
	// Returns empty array if server has no tools.
	// Returns error if server name is empty, server not found, or server not connected.
	GetServerTools(ctx context.Context, name string) ([]map[string]interface{}, error)

	// TriggerOAuthLogin initiates an OAuth 2.x authentication flow for a specific server.
	// Delegates to upstream manager's StartManualOAuth() which launches browser-based flow.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful OAuth completion.
	// Method returns immediately after starting OAuth flow (actual completion is asynchronous).
	// Returns error if server name is empty, server not found, config gates block operation,
	// or server doesn't support OAuth.
	TriggerOAuthLogin(ctx context.Context, name string) error

	// TriggerOAuthLoginQuick initiates OAuth 2.x authentication flow and returns browser status immediately.
	// Unlike TriggerOAuthLogin which runs fully async, this returns actual browser_opened status.
	// Used by HTTP handler to return accurate OAuthStartResponse (Spec 020 fix).
	TriggerOAuthLoginQuick(ctx context.Context, name string) (*core.OAuthStartResult, error)

	// TriggerOAuthLogout clears OAuth token and disconnects a specific server.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful logout.
	// Returns error if server name is empty, server not found, config gates block operation,
	// or server doesn't support OAuth.
	TriggerOAuthLogout(ctx context.Context, name string) error

	// LogoutAllOAuth clears OAuth tokens for all OAuth-enabled servers.
	// Returns BulkOperationResult with success/failure counts.
	// This operation respects disable_management and read_only configuration gates.
	LogoutAllOAuth(ctx context.Context) (*BulkOperationResult, error)
}

Service defines the management interface for all server lifecycle and diagnostic operations. All CLI commands, REST endpoints, and MCP tools delegate to this service.

func NewService

func NewService(
	runtime RuntimeOperations,
	cfg *config.Config,
	eventEmitter EventEmitter,
	secretResolver *secret.Resolver,
	logger *zap.SugaredLogger,
) Service

NewService creates a new management service with the given dependencies. The runtime parameter should implement RuntimeOperations (typically *runtime.Runtime).