Files
CLIProxyAPI/internal/api/server.go
Luis Pater 6acfb76b54 feat(sdk): keep caller-provided interceptor host and executor wrappers across config apply
- Add Builder.WithPluginInterceptorHost so embedders can install a custom PluginInterceptorHost that survives startup and reload; the server wraps it to keep plugin model routing, executor dispatch, lifecycle, and websocket observers delegated to the internal plugin host.
- Add Hooks.OnConfigApplied invoked after each successful config apply so embedders can reinstall executor wrappers and other caller-owned runtime state.
- Cover the delegated interceptor host with nil-safety, skip-forwarding, capability-detection, and real execute-chain regression tests.

Closes: #7499
Co-authored-by: Dylan <1990016@gmail.com>
Co-authored-by: lzt404 <2596933790@qq.com>
2026-11-13 07:53:46 +08:00

519 lines
18 KiB
Go

// Package api provides the HTTP API server implementation for the CLI Proxy API.
// It includes the main server struct, routing setup, middleware for CORS and authentication,
// and integration with various AI API handlers (OpenAI, Claude, Gemini).
// The server supports hot-reloading of clients and configuration.
package api
import (
"context"
"crypto/tls"
"errors"
"fmt"
"net"
"net/http"
"os"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/gin-gonic/gin"
managementHandlers "github.com/router-for-me/CLIProxyAPI/v8/internal/api/handlers/management"
"github.com/router-for-me/CLIProxyAPI/v8/internal/api/middleware"
codexlive "github.com/router-for-me/CLIProxyAPI/v8/internal/client/codex/live"
"github.com/router-for-me/CLIProxyAPI/v8/internal/config"
"github.com/router-for-me/CLIProxyAPI/v8/internal/githubauth"
"github.com/router-for-me/CLIProxyAPI/v8/internal/logging"
"github.com/router-for-me/CLIProxyAPI/v8/internal/managementasset"
"github.com/router-for-me/CLIProxyAPI/v8/internal/pluginhost"
"github.com/router-for-me/CLIProxyAPI/v8/internal/redisqueue"
"github.com/router-for-me/CLIProxyAPI/v8/internal/wstunnel"
sdkaccess "github.com/router-for-me/CLIProxyAPI/v8/sdk/access"
"github.com/router-for-me/CLIProxyAPI/v8/sdk/api/handlers"
"github.com/router-for-me/CLIProxyAPI/v8/sdk/api/handlers/openai"
"github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
log "github.com/sirupsen/logrus"
"golang.org/x/net/http2"
"gopkg.in/yaml.v3"
)
// Server represents the main API server.
// It encapsulates the Gin engine, HTTP server, handlers, and configuration.
type Server struct {
// engine is the Gin web framework engine instance.
engine *gin.Engine
// server is the underlying HTTP server.
server *http.Server
// muxBaseListener is the shared TCP listener used to serve both HTTP and Redis protocol traffic.
listenerMu sync.Mutex
muxBaseListener net.Listener
// muxHTTPListener receives HTTP connections selected by the multiplexer.
muxHTTPListener *muxListener
// handlers contains the API handlers for processing requests.
handlers *handlers.BaseAPIHandler
codexLiveHandler *codexlive.Handler
tunnelHub *wstunnel.Hub
// cfg holds the current server configuration.
cfgMu sync.RWMutex
cfg *config.Config
// oldConfigYaml stores a YAML snapshot of the previous configuration for change detection.
// This prevents issues when the config object is modified in place by Management API.
oldConfigYaml []byte
// accessManager handles request authentication providers.
accessManager *sdkaccess.Manager
// requestLogger is the request logger instance for dynamic configuration updates.
requestLogger logging.RequestLogger
loggerToggle func(bool)
// configFilePath is the absolute path to the YAML config file for persistence.
configFilePath string
// currentPath is the absolute path to the current working directory.
currentPath string
// wsRoutes tracks registered websocket upgrade paths.
wsRouteMu sync.Mutex
wsRoutes map[string]struct{}
wsAuthChanged func(bool, bool)
wsAuthEnabled atomic.Bool
// management handler
mgmt *managementHandlers.Handler
// pluginHost owns dynamic plugin Management API route dispatch.
pluginHost *pluginhost.Host
// interceptorHost is the resolved PluginInterceptorHost installed on request
// handlers. When a caller provides their own host via
// WithPluginInterceptorHost, interceptor calls and capability detection
// delegate to that host while plugin model routing, lifecycle callbacks, and
// websocket observers stay delegated to pluginHost.
interceptorHost handlers.PluginInterceptorHost
// managementRoutesRegistered tracks whether the management routes have been attached to the engine.
managementRoutesRegistered atomic.Bool
// managementRoutesEnabled controls whether management endpoints serve real handlers.
managementRoutesEnabled atomic.Bool
// envManagementSecret indicates whether MANAGEMENT_PASSWORD is configured.
envManagementSecret bool
localPassword string
keepAliveEnabled bool
keepAliveTimeout time.Duration
keepAliveOnTimeout func()
keepAliveHeartbeat chan struct{}
keepAliveStop chan struct{}
exampleAPIKeySafeModeEnabled bool
exampleAPIKeySafeModeActive atomic.Bool
}
// NewServer creates and initializes a new API server instance.
// It sets up the Gin engine, middleware, routes, and handlers.
//
// Parameters:
// - cfg: The server configuration
// - authManager: core runtime auth manager
// - accessManager: request authentication manager
//
// Returns:
// - *Server: A new server instance
func NewServer(cfg *config.Config, authManager *auth.Manager, accessManager *sdkaccess.Manager, configFilePath string, opts ...ServerOption) *Server {
if cfg != nil {
cfg = cfg.CloneForRuntime()
}
optionState := &serverOptionConfig{
requestLoggerFactory: defaultRequestLoggerFactory,
}
for i := range opts {
opts[i](optionState)
}
// Set gin mode
if !cfg.Debug {
gin.SetMode(gin.ReleaseMode)
}
// Create gin engine
engine := gin.New()
if errSetTrustedProxies := engine.SetTrustedProxies(cfg.TrustedProxies); errSetTrustedProxies != nil {
log.WithError(errSetTrustedProxies).Error("invalid trusted-proxies configuration; forwarded client IP headers will be ignored")
if errDisableTrustedProxies := engine.SetTrustedProxies(nil); errDisableTrustedProxies != nil {
log.WithError(errDisableTrustedProxies).Error("failed to disable trusted proxy handling")
}
}
if optionState.engineConfigurator != nil {
optionState.engineConfigurator(engine)
}
wd, err := os.Getwd()
if err != nil {
wd = configFilePath
}
envAdminPassword, envAdminPasswordSet := os.LookupEnv("MANAGEMENT_PASSWORD")
envAdminPassword = strings.TrimSpace(envAdminPassword)
envManagementSecret := envAdminPasswordSet && envAdminPassword != ""
// Create server instance
s := &Server{
engine: engine,
handlers: handlers.NewBaseAPIHandlers(effectiveSDKConfig(cfg), authManager),
tunnelHub: wstunnel.NewHub(wstunnel.Options{}),
cfg: cfg,
accessManager: accessManager,
configFilePath: configFilePath,
currentPath: wd,
envManagementSecret: envManagementSecret,
wsRoutes: make(map[string]struct{}),
pluginHost: optionState.pluginHost,
exampleAPIKeySafeModeEnabled: optionState.exampleAPIKeySafeMode,
}
// Resolve the interceptor host once so startup and reload share the same
// wiring. A caller-provided host keeps interceptor dispatch and capability
// detection on the embedder implementation while model routing, lifecycle
// callbacks, and websocket observers remain delegated to the internal
// plugin host. Typed-nil values are normalized first so they cannot defeat
// SetPluginHost's own nil-interface normalization.
if custom := normalizeInterceptorHost(optionState.pluginInterceptorHost); custom != nil {
s.interceptorHost = &delegatedInterceptorHost{
primary: custom,
pluginHost: optionState.pluginHost,
}
} else {
s.interceptorHost = optionState.pluginHost
}
// Add middleware
engine.Use(logging.GinLogrusLogger())
engine.Use(logging.CPATraceIDMiddleware())
engine.Use(s.maxRequestBodyBytesMiddleware())
// Add request logging middleware before recovery and extra middleware so that
// any panic response written by GinLogrusRecovery or custom extraMiddleware is
// captured before request logging finalizes.
var requestLogger logging.RequestLogger
var toggle func(bool)
if !cfg.CommercialMode {
if optionState.requestLoggerFactory != nil {
requestLogger = optionState.requestLoggerFactory(cfg, configFilePath)
}
if requestLogger != nil {
engine.Use(middleware.RequestLoggingMiddleware(requestLogger))
if setter, ok := requestLogger.(interface{ SetEnabled(bool) }); ok {
toggle = setter.SetEnabled
}
}
}
s.requestLogger = requestLogger
s.loggerToggle = toggle
engine.Use(logging.GinLogrusRecovery())
for _, mw := range optionState.extraMiddleware {
engine.Use(mw)
}
engine.Use(corsMiddleware())
engine.Use(s.responseCompressionMiddleware())
openai.SetResponsesWebsocketCompressionEnabled(cfg.Codex.WebsocketCompressionEnabled())
s.wsAuthEnabled.Store(cfg.WebsocketAuth)
s.exampleAPIKeySafeModeActive.Store(s.exampleAPIKeySafeModeRequired(cfg))
s.handlers.SetPluginHost(s.interceptorHost)
if optionState.pluginHost != nil {
optionState.pluginHost.SetModelExecutor(s.handlers)
optionState.pluginHost.SetAuthManager(authManager)
}
// Save initial YAML snapshot
s.oldConfigYaml, _ = yaml.Marshal(cfg)
s.applyAccessConfig(nil, cfg)
if authManager != nil {
authManager.SetRetryConfig(cfg.RequestRetry, time.Duration(cfg.MaxRetryInterval)*time.Second, cfg.MaxRetryCredentials)
}
githubauth.SetToken(cfg.GitHubToken)
managementasset.SetCurrentConfig(cfg)
auth.SetQuotaCooldownDisabled(cfg.DisableCooling)
auth.SetTransientErrorCooldownSeconds(cfg.TransientErrorCooldownSeconds)
applySignatureCacheConfig(nil, cfg)
applyClaudeToolSearchConfig(cfg)
// Initialize management handler
s.mgmt = managementHandlers.NewHandler(cfg, configFilePath, authManager)
s.mgmt.SetPluginHost(optionState.pluginHost)
s.mgmt.SetConfigReloadHook(optionState.configReloadHook)
if optionState.localPassword != "" {
s.mgmt.SetLocalPassword(optionState.localPassword)
}
logDir := logging.ResolveLogDirectory(cfg)
s.mgmt.SetLogDirectory(logDir)
if optionState.postAuthHook != nil {
s.mgmt.SetPostAuthHook(optionState.postAuthHook)
}
if optionState.postAuthPersistHook != nil {
s.mgmt.SetPostAuthPersistHook(optionState.postAuthPersistHook)
}
s.localPassword = optionState.localPassword
// Home heartbeat gate: when home is enabled, block all endpoints with 503 until the
// subscribe-config heartbeat connection is healthy.
engine.Use(s.homeHeartbeatMiddleware())
engine.Use(s.exampleAPIKeySafeModeMiddleware())
// Setup routes
s.setupRoutes()
// Apply additional router configurators from options
if optionState.routerConfigurator != nil {
optionState.routerConfigurator(engine, s.handlers, cfg)
}
// Register management routes when configuration or environment secrets are available,
// or when a local management password is provided (e.g. TUI mode).
hasManagementSecret := cfg.RemoteManagement.SecretKey != "" || envManagementSecret || s.localPassword != ""
s.managementRoutesEnabled.Store(hasManagementSecret)
redisqueue.SetEnabled(hasManagementSecret || (cfg != nil && cfg.Home.Enabled))
if hasManagementSecret {
s.registerManagementRoutes()
}
s.refreshPluginManagementRoutes()
engine.NoRoute(s.pluginManagementNoRoute)
if optionState.keepAliveEnabled {
s.enableKeepAlive(optionState.keepAliveTimeout, optionState.keepAliveOnTimeout)
}
// Create HTTP server
s.server = &http.Server{
Addr: fmt.Sprintf("%s:%d", cfg.Host, cfg.Port),
Handler: wrapUnconsumedRequestBodyHandler(engine),
ReadHeaderTimeout: muxSniffDeadline,
}
return s
}
func (s *Server) getConfig() *config.Config {
if s == nil {
return nil
}
s.cfgMu.RLock()
defer s.cfgMu.RUnlock()
return s.cfg
}
// Handler returns the HTTP handler used by the server.
func (s *Server) Handler() http.Handler {
if s == nil || s.server == nil {
return nil
}
return s.server.Handler
}
// Start begins listening for and serving HTTP or HTTPS requests.
// It's a blocking call and will only return on an unrecoverable error.
//
// Returns:
// - error: An error if the server fails to start
func (s *Server) Start() error {
if s == nil || s.server == nil {
return fmt.Errorf("failed to start HTTP server: server not initialized")
}
addr := s.server.Addr
listener, errListen := net.Listen("tcp", addr)
if errListen != nil {
return fmt.Errorf("failed to start HTTP server: %v", errListen)
}
cfg := s.getConfig()
useTLS := cfg != nil && cfg.TLS.Enable
if useTLS {
certPath := strings.TrimSpace(cfg.TLS.Cert)
keyPath := strings.TrimSpace(cfg.TLS.Key)
if certPath == "" || keyPath == "" {
if errClose := listener.Close(); errClose != nil {
log.Errorf("failed to close listener after TLS validation failure: %v", errClose)
}
return fmt.Errorf("failed to start HTTPS server: tls.cert or tls.key is empty")
}
certPair, errLoad := tls.LoadX509KeyPair(certPath, keyPath)
if errLoad != nil {
if errClose := listener.Close(); errClose != nil {
log.Errorf("failed to close listener after TLS key pair load failure: %v", errClose)
}
return fmt.Errorf("failed to start HTTPS server: %v", errLoad)
}
tlsConfig := &tls.Config{
Certificates: []tls.Certificate{certPair},
NextProtos: []string{"h2", "http/1.1"},
}
s.server.TLSConfig = tlsConfig
if errHTTP2 := http2.ConfigureServer(s.server, &http2.Server{}); errHTTP2 != nil {
log.Warnf("failed to configure HTTP/2: %v", errHTTP2)
}
listener = tls.NewListener(listener, tlsConfig)
log.Debugf("Starting API server on %s with TLS", addr)
} else {
log.Debugf("Starting API server on %s", addr)
}
httpListener := newMuxListener(listener.Addr(), 1024)
s.listenerMu.Lock()
s.muxBaseListener = listener
s.muxHTTPListener = httpListener
s.listenerMu.Unlock()
httpErrCh := make(chan error, 1)
acceptErrCh := make(chan error, 1)
go func() {
httpErrCh <- s.server.Serve(httpListener)
}()
go func() {
acceptErrCh <- s.acceptMuxConnections(listener, httpListener)
}()
select {
case errServe := <-httpErrCh:
s.listenerMu.Lock()
muxBase := s.muxBaseListener
muxHTTP := s.muxHTTPListener
s.muxBaseListener = nil
s.muxHTTPListener = nil
s.listenerMu.Unlock()
if muxBase != nil {
if errClose := muxBase.Close(); errClose != nil && !errors.Is(errClose, net.ErrClosed) {
log.Debugf("failed to close shared listener after HTTP serve exit: %v", errClose)
}
}
if muxHTTP != nil {
_ = muxHTTP.Close()
}
errAccept := <-acceptErrCh
errServe = normalizeHTTPServeError(errServe)
errAccept = normalizeListenerError(errAccept)
if errServe != nil {
return fmt.Errorf("failed to start HTTP server: %v", errServe)
}
if errAccept != nil {
return fmt.Errorf("failed to start HTTP server: %v", errAccept)
}
return nil
case errAccept := <-acceptErrCh:
s.listenerMu.Lock()
muxHTTP := s.muxHTTPListener
muxBase := s.muxBaseListener
s.muxHTTPListener = nil
s.muxBaseListener = nil
s.listenerMu.Unlock()
if muxHTTP != nil {
_ = muxHTTP.Close()
}
if muxBase != nil {
if errClose := muxBase.Close(); errClose != nil && !errors.Is(errClose, net.ErrClosed) {
log.Debugf("failed to close shared listener after accept loop exit: %v", errClose)
}
}
errServe := <-httpErrCh
errServe = normalizeHTTPServeError(errServe)
errAccept = normalizeListenerError(errAccept)
if errAccept != nil {
return fmt.Errorf("failed to start HTTP server: %v", errAccept)
}
if errServe != nil {
return fmt.Errorf("failed to start HTTP server: %v", errServe)
}
return nil
}
}
// Stop closes listeners and shuts down the API server.
// When server.shutdown-timeout is a positive number of seconds, Stop first lets
// in-flight requests finish within that budget (http.Server.Shutdown), then
// forcibly closes whatever remains. The default 0 closes immediately, preserving
// the behavior introduced to prevent hanging on active requests (#6094).
//
// Parameters:
// - ctx: Context bounding the whole stop operation.
//
// Returns:
// - error: An error if the server fails to stop
func (s *Server) Stop(ctx context.Context) error {
log.Debug("Stopping API server...")
if s.keepAliveEnabled {
select {
case s.keepAliveStop <- struct{}{}:
default:
}
}
s.listenerMu.Lock()
muxHTTP := s.muxHTTPListener
s.muxHTTPListener = nil
muxBase := s.muxBaseListener
s.muxBaseListener = nil
s.listenerMu.Unlock()
if muxHTTP != nil {
_ = muxHTTP.Close()
}
if muxBase != nil {
if errCloseBase := muxBase.Close(); errCloseBase != nil && !errors.Is(errCloseBase, net.ErrClosed) {
log.Debugf("failed to close shared listener: %v", errCloseBase)
}
}
// Close the HTTP server. With a positive server.shutdown-timeout, drain
// in-flight requests for up to that many seconds first; otherwise close
// immediately without graceful draining.
var errCloseServer error
if s.server != nil {
drainTimeout := 0
if cfg := s.getConfig(); cfg != nil {
drainTimeout = cfg.ShutdownTimeoutSeconds
}
if drainTimeout > 0 {
// Bound the drain by the configured timeout even when the caller's
// context is more generous: shutdown must never hang longer than the
// operator chose. A tighter caller deadline still wins via parent ctx.
drainCtx, cancel := context.WithTimeout(ctx, time.Duration(drainTimeout)*time.Second)
defer cancel()
log.Debugf("draining HTTP connections for up to %ds", drainTimeout)
errShutdown := s.server.Shutdown(drainCtx)
if errShutdown != nil && !errors.Is(errShutdown, context.DeadlineExceeded) && !errors.Is(errShutdown, context.Canceled) {
errCloseServer = errShutdown
}
}
// Always force-close afterwards: this terminates anything that outlived
// the drain budget and is a no-op when Shutdown already returned cleanly.
// Hijacked connections (WebSocket sessions) are not tracked by the HTTP
// server; they are released by their own managers below.
if errClose := s.server.Close(); errClose != nil && !errors.Is(errClose, http.ErrServerClosed) && !errors.Is(errClose, net.ErrClosed) && errCloseServer == nil {
errCloseServer = errClose
}
}
if s.codexLiveHandler != nil {
s.codexLiveHandler.Close()
}
if s.tunnelHub != nil {
s.tunnelHub.Close()
}
if errCloseServer != nil {
return fmt.Errorf("failed to shutdown HTTP server: %v", errCloseServer)
}
log.Debug("API server stopped")
return nil
}