Documentation
¶
Overview ¶
Package management provides the management API handlers and middleware for configuring the server and managing auth files.
Index ¶
- func CompleteOAuthSession(state string)
- func CompleteOAuthSessionsByProvider(provider string) int
- func CompletePluginOAuthSessionsByProvider(provider string) int
- func GetOAuthSession(state string) (provider string, status string, ok bool)
- func GetOAuthSessionDetails(state string) (provider string, status string, isPlugin bool, metadata map[string]any, ...)
- func IsOAuthSessionPending(state, provider string) bool
- func NormalizeOAuthProvider(provider string) (string, error)
- func PopulateAuthContext(ctx context.Context, c *gin.Context) context.Context
- func RegisterOAuthSession(state, provider string)
- func RegisterPluginOAuthSession(state, provider string, metadata map[string]any) error
- func SetOAuthSessionError(state, message string)
- func ValidateOAuthState(state string) error
- func WriteConfig(path string, data []byte) error
- func WriteOAuthCallbackFile(authDir, provider, state, code, errorMessage string) (string, error)
- func WriteOAuthCallbackFileForPendingSession(authDir, provider, state, code, errorMessage string) (string, error)
- type Handler
- func (h *Handler) APICall(c *gin.Context)
- func (h *Handler) AuthenticateManagementKey(clientIP string, localClient bool, provided string) (bool, int, string)
- func (h *Handler) DeleteAPIKeys(c *gin.Context)
- func (h *Handler) DeleteAuthFile(c *gin.Context)
- func (h *Handler) DeleteClaudeKey(c *gin.Context)
- func (h *Handler) DeleteCodexKey(c *gin.Context)
- func (h *Handler) DeleteGeminiKey(c *gin.Context)
- func (h *Handler) DeleteLogs(c *gin.Context)
- func (h *Handler) DeleteOAuthExcludedModels(c *gin.Context)
- func (h *Handler) DeleteOAuthModelAlias(c *gin.Context)
- func (h *Handler) DeleteOpenAICompat(c *gin.Context)
- func (h *Handler) DeletePlugin(c *gin.Context)
- func (h *Handler) DeleteProxyURL(c *gin.Context)
- func (h *Handler) DeleteVertexCompatKey(c *gin.Context)
- func (h *Handler) DownloadAuthFile(c *gin.Context)
- func (h *Handler) DownloadRequestErrorLog(c *gin.Context)
- func (h *Handler) GetAPIKeyUsage(c *gin.Context)
- func (h *Handler) GetAPIKeys(c *gin.Context)
- func (h *Handler) GetAuthFileModels(c *gin.Context)
- func (h *Handler) GetAuthStatus(c *gin.Context)
- func (h *Handler) GetClaudeKeys(c *gin.Context)
- func (h *Handler) GetCodexKeys(c *gin.Context)
- func (h *Handler) GetConfig(c *gin.Context)
- func (h *Handler) GetConfigYAML(c *gin.Context)
- func (h *Handler) GetDebug(c *gin.Context)
- func (h *Handler) GetErrorLogsMaxFiles(c *gin.Context)
- func (h *Handler) GetForceModelPrefix(c *gin.Context)
- func (h *Handler) GetGeminiKeys(c *gin.Context)
- func (h *Handler) GetLatestVersion(c *gin.Context)
- func (h *Handler) GetLoggingToFile(c *gin.Context)
- func (h *Handler) GetLogs(c *gin.Context)
- func (h *Handler) GetLogsMaxTotalSizeMB(c *gin.Context)
- func (h *Handler) GetMaxRetryInterval(c *gin.Context)
- func (h *Handler) GetOAuthExcludedModels(c *gin.Context)
- func (h *Handler) GetOAuthModelAlias(c *gin.Context)
- func (h *Handler) GetOpenAICompat(c *gin.Context)
- func (h *Handler) GetPluginConfig(c *gin.Context)
- func (h *Handler) GetProxyURL(c *gin.Context)
- func (h *Handler) GetRequestErrorLogs(c *gin.Context)
- func (h *Handler) GetRequestLog(c *gin.Context)
- func (h *Handler) GetRequestLogByID(c *gin.Context)
- func (h *Handler) GetRequestRetry(c *gin.Context)
- func (h *Handler) GetRoutingStrategy(c *gin.Context)
- func (h *Handler) GetStaticModelDefinitions(c *gin.Context)
- func (h *Handler) GetSwitchPreviewModel(c *gin.Context)
- func (h *Handler) GetSwitchProject(c *gin.Context)
- func (h *Handler) GetUsageQueue(c *gin.Context)
- func (h *Handler) GetUsageStatisticsEnabled(c *gin.Context)
- func (h *Handler) GetVertexCompatKeys(c *gin.Context)
- func (h *Handler) GetWebsocketAuth(c *gin.Context)
- func (h *Handler) ImportVertexCredential(c *gin.Context)
- func (h *Handler) InstallPluginFromStore(c *gin.Context)
- func (h *Handler) ListAuthFiles(c *gin.Context)
- func (h *Handler) ListPluginStore(c *gin.Context)
- func (h *Handler) ListPlugins(c *gin.Context)
- func (h *Handler) Middleware() gin.HandlerFunc
- func (h *Handler) PatchAPIKeys(c *gin.Context)
- func (h *Handler) PatchAuthFileFields(c *gin.Context)
- func (h *Handler) PatchAuthFileStatus(c *gin.Context)
- func (h *Handler) PatchClaudeKey(c *gin.Context)
- func (h *Handler) PatchCodexKey(c *gin.Context)
- func (h *Handler) PatchGeminiKey(c *gin.Context)
- func (h *Handler) PatchOAuthExcludedModels(c *gin.Context)
- func (h *Handler) PatchOAuthModelAlias(c *gin.Context)
- func (h *Handler) PatchOpenAICompat(c *gin.Context)
- func (h *Handler) PatchPluginConfig(c *gin.Context)
- func (h *Handler) PatchPluginEnabled(c *gin.Context)
- func (h *Handler) PatchVertexCompatKey(c *gin.Context)
- func (h *Handler) PostOAuthCallback(c *gin.Context)
- func (h *Handler) PutAPIKeys(c *gin.Context)
- func (h *Handler) PutClaudeKeys(c *gin.Context)
- func (h *Handler) PutCodexKeys(c *gin.Context)
- func (h *Handler) PutConfigYAML(c *gin.Context)
- func (h *Handler) PutDebug(c *gin.Context)
- func (h *Handler) PutErrorLogsMaxFiles(c *gin.Context)
- func (h *Handler) PutForceModelPrefix(c *gin.Context)
- func (h *Handler) PutGeminiKeys(c *gin.Context)
- func (h *Handler) PutLoggingToFile(c *gin.Context)
- func (h *Handler) PutLogsMaxTotalSizeMB(c *gin.Context)
- func (h *Handler) PutMaxRetryInterval(c *gin.Context)
- func (h *Handler) PutOAuthExcludedModels(c *gin.Context)
- func (h *Handler) PutOAuthModelAlias(c *gin.Context)
- func (h *Handler) PutOpenAICompat(c *gin.Context)
- func (h *Handler) PutPluginConfig(c *gin.Context)
- func (h *Handler) PutProxyURL(c *gin.Context)
- func (h *Handler) PutRequestLog(c *gin.Context)
- func (h *Handler) PutRequestRetry(c *gin.Context)
- func (h *Handler) PutRoutingStrategy(c *gin.Context)
- func (h *Handler) PutSwitchPreviewModel(c *gin.Context)
- func (h *Handler) PutSwitchProject(c *gin.Context)
- func (h *Handler) PutUsageStatisticsEnabled(c *gin.Context)
- func (h *Handler) PutVertexCompatKeys(c *gin.Context)
- func (h *Handler) PutWebsocketAuth(c *gin.Context)
- func (h *Handler) RequestAnthropicToken(c *gin.Context)
- func (h *Handler) RequestAntigravityToken(c *gin.Context)
- func (h *Handler) RequestCodexToken(c *gin.Context)
- func (h *Handler) RequestKimiToken(c *gin.Context)
- func (h *Handler) RequestXAIToken(c *gin.Context)
- func (h *Handler) ServePluginAuthURL(c *gin.Context) bool
- func (h *Handler) SetAuthManager(manager *coreauth.Manager)
- func (h *Handler) SetConfig(cfg *config.Config)
- func (h *Handler) SetConfigReloadHook(hook func(context.Context, *config.Config))
- func (h *Handler) SetLocalPassword(password string)
- func (h *Handler) SetLogDirectory(dir string)
- func (h *Handler) SetPluginHost(host *pluginhost.Host)
- func (h *Handler) SetPostAuthHook(hook coreauth.PostAuthHook)
- func (h *Handler) SetPostAuthPersistHook(hook coreauth.PostAuthHook)
- func (h *Handler) UploadAuthFile(c *gin.Context)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompleteOAuthSession ¶
func CompleteOAuthSession(state string)
func CompletePluginOAuthSessionsByProvider ¶ added in v7.1.47
func GetOAuthSessionDetails ¶ added in v7.1.47
func IsOAuthSessionPending ¶
func NormalizeOAuthProvider ¶
func PopulateAuthContext ¶
PopulateAuthContext extracts request info and adds it to the context
func RegisterOAuthSession ¶
func RegisterOAuthSession(state, provider string)
func RegisterPluginOAuthSession ¶ added in v7.1.47
func SetOAuthSessionError ¶
func SetOAuthSessionError(state, message string)
func ValidateOAuthState ¶
func WriteConfig ¶
func WriteOAuthCallbackFile ¶
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler aggregates config reference, persistence path and helpers.
func NewHandler ¶
NewHandler creates a new management handler instance.
func NewHandlerWithoutConfigFilePath ¶
NewHandler creates a new management handler instance.
func (*Handler) APICall ¶
APICall makes a generic HTTP request on behalf of the management API caller. It is protected by the management middleware.
Endpoint:
POST /v0/management/api-call
Authentication:
Same as other management APIs (requires a management key and remote-management rules). You can provide the key via: - Authorization: Bearer <key> - X-Management-Key: <key>
Request JSON:
- auth_index / authIndex / AuthIndex (optional): The credential "auth_index" from GET /v0/management/auth-files (or other endpoints returning it). If omitted or not found, credential-specific proxy/token substitution is skipped.
- method (required): HTTP method, e.g. GET, POST, PUT, PATCH, DELETE.
- url (required): Absolute URL including scheme and host, e.g. "https://api.example.com/v1/ping".
- header (optional): Request headers map. Supports magic variable "$TOKEN$" which is replaced using the selected credential: 1) metadata.access_token 2) attributes.api_key 3) metadata.token / metadata.id_token / metadata.cookie Example: {"Authorization":"Bearer $TOKEN$"}. Note: if you need to override the HTTP Host header, set header["Host"].
- data (optional): Raw request body as string (useful for POST/PUT/PATCH).
Proxy selection (highest priority first):
- Selected credential proxy_url
- Global config proxy-url
- Direct connect (environment proxies are not used)
Response JSON (returned with HTTP 200 when the APICall itself succeeds):
- status_code: Upstream HTTP status code.
- header: Upstream response headers.
- body: Upstream response body as string.
Example:
curl -sS -X POST "http://127.0.0.1:8317/v0/management/api-call" \
-H "Authorization: Bearer <MANAGEMENT_KEY>" \
-H "Content-Type: application/json" \
-d '{"auth_index":"<AUTH_INDEX>","method":"GET","url":"https://api.example.com/v1/ping","header":{"Authorization":"Bearer $TOKEN$"}}'
curl -sS -X POST "http://127.0.0.1:8317/v0/management/api-call" \
-H "Authorization: Bearer 831227" \
-H "Content-Type: application/json" \
-d '{"auth_index":"<AUTH_INDEX>","method":"POST","url":"https://api.example.com/v1/fetchAvailableModels","header":{"Authorization":"Bearer $TOKEN$","Content-Type":"application/json","User-Agent":"cliproxyapi"},"data":"{}"}'
func (*Handler) AuthenticateManagementKey ¶
func (h *Handler) AuthenticateManagementKey(clientIP string, localClient bool, provided string) (bool, int, string)
AuthenticateManagementKey verifies the provided management key for the given client. It mirrors the behaviour of Middleware() so non-HTTP callers can reuse the same logic.
func (*Handler) DeleteAPIKeys ¶
func (*Handler) DeleteAuthFile ¶
Delete auth files: single by name or all
func (*Handler) DeleteClaudeKey ¶
func (*Handler) DeleteCodexKey ¶
func (*Handler) DeleteGeminiKey ¶
func (*Handler) DeleteLogs ¶
DeleteLogs removes all rotated log files and truncates the active log.
func (*Handler) DeleteOAuthExcludedModels ¶
func (*Handler) DeleteOAuthModelAlias ¶
func (*Handler) DeleteOpenAICompat ¶
func (*Handler) DeletePlugin ¶ added in v7.1.75
DeletePlugin removes the selected local plugin file and its saved config.
func (*Handler) DeleteProxyURL ¶
func (*Handler) DeleteVertexCompatKey ¶
func (*Handler) DownloadAuthFile ¶
Download single auth file by name
func (*Handler) DownloadRequestErrorLog ¶
DownloadRequestErrorLog downloads a specific error request log file by name.
func (*Handler) GetAPIKeyUsage ¶
GetAPIKeyUsage returns recent request buckets for all in-memory api_key auths, grouped by provider and keyed by "base_url|api_key".
func (*Handler) GetAuthFileModels ¶
GetAuthFileModels returns the models supported by a specific auth file
func (*Handler) GetAuthStatus ¶
func (*Handler) GetClaudeKeys ¶
claude-api-key: []ClaudeKey
func (*Handler) GetCodexKeys ¶
codex-api-key: []CodexKey
func (*Handler) GetConfigYAML ¶
GetConfigYAML returns the raw config.yaml file bytes without re-encoding. It preserves comments and original formatting/styles.
func (*Handler) GetErrorLogsMaxFiles ¶
ErrorLogsMaxFiles
func (*Handler) GetForceModelPrefix ¶
ForceModelPrefix
func (*Handler) GetGeminiKeys ¶
gemini-api-key: []GeminiKey
func (*Handler) GetLatestVersion ¶
GetLatestVersion returns the latest release version from GitHub without downloading assets.
func (*Handler) GetLoggingToFile ¶
UsageStatisticsEnabled
func (*Handler) GetLogs ¶
GetLogs returns log lines with optional incremental loading.
The legacy timestamp path keeps line-count as the total scanned line count for compatibility. Cursor and tail reads avoid scanning older files, so line-count is the number of returned lines there. A cursor emitted by the legacy path points at the latest complete log boundary; combining after with limit is therefore tail semantics and does not replay lines trimmed by limit.
func (*Handler) GetLogsMaxTotalSizeMB ¶
LogsMaxTotalSizeMB
func (*Handler) GetMaxRetryInterval ¶
Max retry interval
func (*Handler) GetOAuthExcludedModels ¶
oauth-excluded-models: map[string][]string
func (*Handler) GetOAuthModelAlias ¶
oauth-model-alias: map[string][]OAuthModelAlias
func (*Handler) GetOpenAICompat ¶
openai-compatibility: []OpenAICompatibility
func (*Handler) GetPluginConfig ¶ added in v7.1.72
GetPluginConfig returns the preserved plugins.configs.<id> object as JSON.
func (*Handler) GetRequestErrorLogs ¶
GetRequestErrorLogs lists error request log files when RequestLog is disabled. It returns an empty list when RequestLog is enabled.
func (*Handler) GetRequestLogByID ¶
GetRequestLogByID finds and downloads a request log file by its request ID. The ID is matched against the suffix of log file names (format: *-{requestID}.log).
func (*Handler) GetRoutingStrategy ¶
RoutingStrategy
func (*Handler) GetStaticModelDefinitions ¶
GetStaticModelDefinitions returns static model metadata for a given channel. Channel is provided via path param (:channel) or query param (?channel=...).
func (*Handler) GetSwitchPreviewModel ¶
func (*Handler) GetSwitchProject ¶
Quota exceeded toggles
func (*Handler) GetUsageQueue ¶
GetUsageQueue pops queued usage records from the usage queue.
func (*Handler) GetUsageStatisticsEnabled ¶
UsageStatisticsEnabled
func (*Handler) GetVertexCompatKeys ¶
vertex-api-key: []VertexCompatKey
func (*Handler) GetWebsocketAuth ¶
Websocket auth
func (*Handler) ImportVertexCredential ¶
ImportVertexCredential handles uploading a Vertex service account JSON and saving it as an auth record.
func (*Handler) InstallPluginFromStore ¶ added in v7.1.69
func (*Handler) ListAuthFiles ¶
func (*Handler) ListPluginStore ¶ added in v7.1.69
func (*Handler) ListPlugins ¶ added in v7.1.47
ListPlugins returns discovered, configured, and registered plugin entries.
func (*Handler) Middleware ¶
func (h *Handler) Middleware() gin.HandlerFunc
Middleware enforces access control for management endpoints. All requests (local and remote) require a valid management key. Additionally, remote access requires allow-remote-management=true.
func (*Handler) PatchAPIKeys ¶
func (*Handler) PatchAuthFileFields ¶
PatchAuthFileFields updates arbitrary metadata fields of an auth file.
func (*Handler) PatchAuthFileStatus ¶
PatchAuthFileStatus toggles the disabled state of an auth file
func (*Handler) PatchClaudeKey ¶
func (*Handler) PatchCodexKey ¶
func (*Handler) PatchGeminiKey ¶
func (*Handler) PatchOAuthExcludedModels ¶
func (*Handler) PatchOAuthModelAlias ¶
func (*Handler) PatchOpenAICompat ¶
func (*Handler) PatchPluginConfig ¶ added in v7.1.47
PatchPluginConfig shallow-merges plugins.configs.<id> with the request object.
func (*Handler) PatchPluginEnabled ¶ added in v7.1.47
PatchPluginEnabled updates plugins.configs.<id>.enabled without touching plugins.enabled.
func (*Handler) PatchVertexCompatKey ¶
func (*Handler) PostOAuthCallback ¶
func (*Handler) PutAPIKeys ¶
func (*Handler) PutClaudeKeys ¶
func (*Handler) PutCodexKeys ¶
func (*Handler) PutConfigYAML ¶
func (*Handler) PutErrorLogsMaxFiles ¶
func (*Handler) PutForceModelPrefix ¶
func (*Handler) PutGeminiKeys ¶
func (*Handler) PutLoggingToFile ¶
func (*Handler) PutLogsMaxTotalSizeMB ¶
func (*Handler) PutMaxRetryInterval ¶
func (*Handler) PutOAuthExcludedModels ¶
func (*Handler) PutOAuthModelAlias ¶
func (*Handler) PutOpenAICompat ¶
func (*Handler) PutPluginConfig ¶ added in v7.1.47
PutPluginConfig replaces plugins.configs.<id> with the request object.
func (*Handler) PutProxyURL ¶
func (*Handler) PutRequestLog ¶
func (*Handler) PutRequestRetry ¶
func (*Handler) PutRoutingStrategy ¶
func (*Handler) PutSwitchPreviewModel ¶
func (*Handler) PutSwitchProject ¶
func (*Handler) PutUsageStatisticsEnabled ¶
func (*Handler) PutVertexCompatKeys ¶
func (*Handler) PutWebsocketAuth ¶
func (*Handler) RequestAnthropicToken ¶
func (*Handler) RequestAntigravityToken ¶
func (*Handler) RequestCodexToken ¶
func (*Handler) RequestKimiToken ¶
func (*Handler) RequestXAIToken ¶ added in v7.1.0
func (*Handler) ServePluginAuthURL ¶ added in v7.1.47
func (*Handler) SetAuthManager ¶
SetAuthManager updates the auth manager reference used by management endpoints.
func (*Handler) SetConfig ¶
SetConfig updates the in-memory config reference when the server hot-reloads.
func (*Handler) SetConfigReloadHook ¶ added in v7.1.70
SetConfigReloadHook updates the callback used after management saves config changes.
func (*Handler) SetLocalPassword ¶
SetLocalPassword configures the runtime-local password accepted for localhost requests.
func (*Handler) SetLogDirectory ¶
SetLogDirectory updates the directory where main.log should be looked up.
func (*Handler) SetPluginHost ¶ added in v7.1.47
func (h *Handler) SetPluginHost(host *pluginhost.Host)
SetPluginHost updates the plugin host used by plugin-backed management endpoints.
func (*Handler) SetPostAuthHook ¶
func (h *Handler) SetPostAuthHook(hook coreauth.PostAuthHook)
SetPostAuthHook registers a hook to be called after auth record creation but before persistence.
func (*Handler) SetPostAuthPersistHook ¶ added in v7.1.47
func (h *Handler) SetPostAuthPersistHook(hook coreauth.PostAuthHook)
SetPostAuthPersistHook registers a hook to be called after auth persistence.
func (*Handler) UploadAuthFile ¶
Upload auth file: multipart or raw JSON with ?name=
Source Files