mirror of
https://github.com/router-for-me/CLIProxyAPI.git
synced 2026-11-16 22:57:53 +08:00
- 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>
519 lines
18 KiB
Go
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
|
|
}
|