Documentation
¶
Overview ¶
Package util provides utility functions used across the CLIProxyAPI application. These functions handle common tasks such as determining AI service providers from model names and managing HTTP proxies.
Package util provides utility functions for the CLI Proxy API server. It includes helper functions for proxy configuration, HTTP client setup, log level management, and other common operations used across the application.
Package util provides helper functions for SSH tunnel instructions and network-related tasks. This includes detecting the appropriate IP address and printing commands to help users connect to the local server from a remote machine.
Package util provides utility functions for the CLI Proxy API server. It includes helper functions for JSON manipulation, proxy configuration, and other common operations used across the application.
Package util provides utility functions for the CLI Proxy API server. It includes helper functions for logging configuration, file system operations, and other common utilities used throughout the application.
Index ¶
- Constants
- func ApplyClaudeThinkingConfig(body []byte, budget *int) []byte
- func ApplyCustomHeadersFromAttrs(r *http.Request, attrs map[string]string)
- func ApplyDefaultThinkingIfNeeded(model string, body []byte) []byte
- func ApplyDefaultThinkingIfNeededCLI(model string, body []byte) []byte
- func ApplyGeminiCLIThinkingConfig(body []byte, budget *int, includeThoughts *bool) []byte
- func ApplyGeminiThinkingConfig(body []byte, budget *int, includeThoughts *bool) []byte
- func ConvertThinkingLevelToBudget(body []byte) []byte
- func CountAuthFiles(authDir string) int
- func CreateWhiteImageBase64(aspectRatio string) (string, error)
- func DeleteKey(jsonStr, keyName string) string
- func FixJSON(input string) string
- func GetIPAddress() string
- func GetModelThinkingLevels(model string) []string
- func GetOpenAICompatibilityConfig(alias string, cfg *config.Config) (*config.OpenAICompatibility, *config.OpenAICompatibilityModel)
- func GetProviderName(modelName string) []string
- func HideAPIKey(apiKey string) string
- func InArray(hystack []string, needle string) bool
- func IsOpenAICompatibilityAlias(modelName string, cfg *config.Config) bool
- func MaskAuthorizationHeader(value string) string
- func MaskSensitiveHeaderValue(key, value string) string
- func MaskSensitiveQuery(raw string) string
- func ModelHasDefaultThinking(model string) bool
- func ModelSupportsThinking(model string) bool
- func ModelUsesThinkingLevels(model string) bool
- func NormalizeGeminiCLIThinkingBudget(model string, body []byte) []byte
- func NormalizeGeminiThinkingBudget(model string, body []byte) []byte
- func NormalizeReasoningEffortLevel(model, effort string) (string, bool)
- func NormalizeThinkingBudget(model string, budget int) int
- func NormalizeThinkingModel(modelName string) (string, map[string]any)
- func PrintSSHTunnelInstructions(port int)
- func ReasoningEffortFromMetadata(metadata map[string]any) (string, bool)
- func RenameKey(jsonStr, oldKeyPath, newKeyPath string) (string, error)
- func ResolveAuthDir(authDir string) (string, error)
- func ResolveAutoModel(modelName string) string
- func ResolveClaudeThinkingConfig(modelName string, metadata map[string]any) (*int, bool)
- func ResolveOriginalModel(model string, metadata map[string]any) string
- func ResolveThinkingConfigFromMetadata(model string, metadata map[string]any) (*int, *bool, bool)
- func SetLogLevel(cfg *config.Config)
- func SetProxy(cfg *config.SDKConfig, httpClient *http.Client) *http.Client
- func StripThinkingConfigIfUnsupported(model string, body []byte) []byte
- func ThinkingEffortToBudget(model, effort string) (int, bool)
- func ThinkingFromMetadata(metadata map[string]any) (*int, *bool, *string, bool)
- func Walk(value gjson.Result, path, field string, paths *[]string)
- func WritablePath() string
Constants ¶
const ( GeminiThinkingBudgetMetadataKey = "gemini_thinking_budget" GeminiIncludeThoughtsMetadataKey = "gemini_include_thoughts" GeminiOriginalModelMetadataKey = "gemini_original_model" )
const ( ThinkingBudgetMetadataKey = "thinking_budget" ThinkingIncludeThoughtsMetadataKey = "thinking_include_thoughts" ReasoningEffortMetadataKey = "reasoning_effort" ThinkingOriginalModelMetadataKey = "thinking_original_model" )
Variables ¶
This section is empty.
Functions ¶
func ApplyClaudeThinkingConfig ¶ added in v6.6.1
ApplyClaudeThinkingConfig applies thinking configuration to a Claude API request payload. It sets the thinking.type to "enabled" and thinking.budget_tokens to the specified budget. If budget is nil or the payload already has thinking config, it returns the payload unchanged.
func ApplyCustomHeadersFromAttrs ¶ added in v6.3.23
ApplyCustomHeadersFromAttrs applies user-defined headers stored in the provided attributes map. Custom headers override built-in defaults when conflicts occur.
func ApplyDefaultThinkingIfNeeded ¶ added in v6.5.60
ApplyDefaultThinkingIfNeeded injects default thinkingConfig for models that require it. For standard Gemini API format (generationConfig.thinkingConfig path). Returns the modified body if thinkingConfig was added, otherwise returns the original.
func ApplyDefaultThinkingIfNeededCLI ¶ added in v6.5.60
ApplyDefaultThinkingIfNeededCLI injects default thinkingConfig for models that require it. For Gemini CLI API format (request.generationConfig.thinkingConfig path). Returns the modified body if thinkingConfig was added, otherwise returns the original.
func ApplyGeminiCLIThinkingConfig ¶ added in v6.2.14
func ApplyGeminiThinkingConfig ¶ added in v6.2.14
func ConvertThinkingLevelToBudget ¶ added in v6.4.1
ConvertThinkingLevelToBudget checks for "generationConfig.thinkingConfig.thinkingLevel" and converts it to "thinkingBudget". "high" -> 32768 "low" -> 128 It removes "thinkingLevel" after conversion.
func CountAuthFiles ¶
CountAuthFiles returns the number of JSON auth files located under the provided directory. The function resolves leading tildes to the user's home directory and performs a case-insensitive match on the ".json" suffix so that files saved with uppercase extensions are also counted.
func CreateWhiteImageBase64 ¶ added in v6.1.13
func FixJSON ¶
FixJSON converts non-standard JSON that uses single quotes for strings into RFC 8259-compliant JSON by converting those single-quoted strings to double-quoted strings with proper escaping.
Examples:
{'a': 1, 'b': '2'} => {"a": 1, "b": "2"}
{"t": 'He said "hi"'} => {"t": "He said \"hi\""}
Rules:
- Existing double-quoted JSON strings are preserved as-is.
- Single-quoted strings are converted to double-quoted strings.
- Inside converted strings, any double quote is escaped (\").
- Common backslash escapes (\n, \r, \t, \b, \f, \\) are preserved.
- \' inside single-quoted strings becomes a literal ' in the output (no escaping needed inside double quotes).
- Unicode escapes (\uXXXX) inside single-quoted strings are forwarded.
- The function does not attempt to fix other non-JSON features beyond quotes.
func GetIPAddress ¶
func GetIPAddress() string
GetIPAddress attempts to find the best-available IP address. It first tries to get the public IP address, and if that fails, it falls back to getting the local outbound IP address.
Returns:
- string: The determined IP address (preferring public IPv4)
func GetModelThinkingLevels ¶ added in v6.6.1
GetModelThinkingLevels returns the discrete reasoning effort levels for the model. Returns nil if the model has no thinking support or no levels defined.
func GetOpenAICompatibilityConfig ¶
func GetOpenAICompatibilityConfig(alias string, cfg *config.Config) (*config.OpenAICompatibility, *config.OpenAICompatibilityModel)
GetOpenAICompatibilityConfig returns the OpenAI compatibility configuration and model details for the given alias.
Parameters:
- alias: The model alias to find configuration for
- cfg: The application configuration containing OpenAI compatibility settings
Returns:
- *config.OpenAICompatibility: The matching compatibility configuration, or nil if not found
- *config.OpenAICompatibilityModel: The matching model configuration, or nil if not found
func GetProviderName ¶
GetProviderName determines all AI service providers capable of serving a registered model. It first queries the global model registry to retrieve the providers backing the supplied model name. When the model has not been registered yet, it falls back to legacy string heuristics to infer potential providers.
Supported providers include (but are not limited to):
- "gemini" for Google's Gemini family
- "codex" for OpenAI GPT-compatible providers
- "claude" for Anthropic models
- "qwen" for Alibaba's Qwen models
- "openai-compatibility" for external OpenAI-compatible providers
Parameters:
- modelName: The name of the model to identify providers for.
- cfg: The application configuration containing OpenAI compatibility settings.
Returns:
- []string: All provider identifiers capable of serving the model, ordered by preference.
func HideAPIKey ¶
HideAPIKey obscures an API key for logging purposes, showing only the first and last few characters.
Parameters:
- apiKey: The API key to hide.
Returns:
- string: The obscured API key.
func InArray ¶
InArray checks if a string exists in a slice of strings. It iterates through the slice and returns true if the target string is found, otherwise it returns false.
Parameters:
- hystack: The slice of strings to search in
- needle: The string to search for
Returns:
- bool: True if the string is found, false otherwise
func IsOpenAICompatibilityAlias ¶
IsOpenAICompatibilityAlias checks if the given model name is an alias configured for OpenAI compatibility routing.
Parameters:
- modelName: The model name to check
- cfg: The application configuration containing OpenAI compatibility settings
Returns:
- bool: True if the model name is an OpenAI compatibility alias, false otherwise
func MaskAuthorizationHeader ¶ added in v6.2.22
maskAuthorizationHeader masks the Authorization header value while preserving the auth type prefix. Common formats: "Bearer <token>", "Basic <credentials>", "ApiKey <key>", etc. It preserves the prefix (e.g., "Bearer ") and only masks the token/credential part.
Parameters:
- value: The Authorization header value
Returns:
- string: The masked Authorization value with prefix preserved
func MaskSensitiveHeaderValue ¶ added in v6.2.22
MaskSensitiveHeaderValue masks sensitive header values while preserving expected formats.
Behavior by header key (case-insensitive):
- "Authorization": Preserve the auth type prefix (e.g., "Bearer ") and mask only the credential part.
- Headers containing "api-key": Mask the entire value using HideAPIKey.
- Others: Return the original value unchanged.
Parameters:
- key: The HTTP header name to inspect (case-insensitive matching).
- value: The header value to mask when sensitive.
Returns:
- string: The masked value according to the header type; unchanged if not sensitive.
func MaskSensitiveQuery ¶ added in v6.2.33
MaskSensitiveQuery masks sensitive query parameters, e.g. auth_token, within the raw query string.
func ModelHasDefaultThinking ¶ added in v6.5.60
ModelHasDefaultThinking returns true if the model should have thinking enabled by default.
func ModelSupportsThinking ¶ added in v6.3.0
ModelSupportsThinking reports whether the given model has Thinking capability according to the model registry metadata (provider-agnostic).
func ModelUsesThinkingLevels ¶ added in v6.6.1
ModelUsesThinkingLevels reports whether the model uses discrete reasoning effort levels instead of numeric budgets.
func NormalizeGeminiCLIThinkingBudget ¶ added in v6.5.60
NormalizeGeminiCLIThinkingBudget normalizes the thinkingBudget value in a Gemini CLI request body (request.generationConfig.thinkingConfig.thinkingBudget path).
func NormalizeGeminiThinkingBudget ¶ added in v6.5.60
NormalizeGeminiThinkingBudget normalizes the thinkingBudget value in a standard Gemini request body (generationConfig.thinkingConfig.thinkingBudget path).
func NormalizeReasoningEffortLevel ¶ added in v6.6.1
NormalizeReasoningEffortLevel validates and normalizes a reasoning effort level for the given model. Returns false when the level is not supported.
func NormalizeThinkingBudget ¶ added in v6.3.0
NormalizeThinkingBudget clamps the requested thinking budget to the supported range for the specified model using registry metadata only. If the model is unknown or has no Thinking metadata, returns the original budget. For dynamic (-1), returns -1 if DynamicAllowed; otherwise approximates mid-range or min (0 if zero is allowed and mid <= 0).
func NormalizeThinkingModel ¶ added in v6.6.0
NormalizeThinkingModel parses dynamic thinking suffixes on model names and returns the normalized base model with extracted metadata. Supported pattern:
- "(<value>)" where value can be:
- A numeric budget (e.g., "(8192)", "(16384)")
- A reasoning effort level (e.g., "(high)", "(medium)", "(low)")
Examples:
- "claude-sonnet-4-5-20250929(16384)" → budget=16384
- "gpt-5.1(high)" → reasoning_effort="high"
- "gemini-2.5-pro(32768)" → budget=32768
Note: Empty parentheses "()" are not supported and will be ignored.
func PrintSSHTunnelInstructions ¶
func PrintSSHTunnelInstructions(port int)
PrintSSHTunnelInstructions detects the IP address and prints SSH tunnel instructions for the user to connect to the local OAuth callback server from a remote machine.
Parameters:
- port: The local port number for the SSH tunnel
func ReasoningEffortFromMetadata ¶ added in v6.6.0
ReasoningEffortFromMetadata resolves a reasoning effort string from metadata, inferring "auto" and "none" when budgets request dynamic or disabled thinking.
func RenameKey ¶
RenameKey renames a key in a JSON string by moving its value to a new key path and then deleting the old key path.
Parameters:
- jsonStr: The JSON string to modify
- oldKeyPath: The dot-notation path to the key that should be renamed
- newKeyPath: The dot-notation path where the value should be moved to
Returns:
- string: The modified JSON string with the key renamed
- error: An error if the operation fails
The function performs the rename in two steps: 1. Sets the value at the new key path 2. Deletes the old key path
func ResolveAuthDir ¶ added in v6.0.10
ResolveAuthDir normalizes the auth directory path for consistent reuse throughout the app. It expands a leading tilde (~) to the user's home directory and returns a cleaned path.
func ResolveAutoModel ¶ added in v6.3.35
ResolveAutoModel resolves the "auto" model name to an actual available model. It uses an empty handler type to get any available model from the registry.
Parameters:
- modelName: The model name to check (should be "auto")
Returns:
- string: The resolved model name, or the original if not "auto" or resolution fails
func ResolveClaudeThinkingConfig ¶ added in v6.6.1
ResolveClaudeThinkingConfig resolves thinking configuration from metadata for Claude models. It uses the unified ResolveThinkingConfigFromMetadata and normalizes the budget. Returns the normalized budget (nil if thinking should not be enabled) and whether it matched.
func ResolveOriginalModel ¶ added in v6.6.0
ResolveOriginalModel returns the original model name stored in metadata (if present), otherwise falls back to the provided model.
func ResolveThinkingConfigFromMetadata ¶ added in v6.6.0
ResolveThinkingConfigFromMetadata derives thinking budget/include overrides, converting reasoning effort strings into budgets when possible.
func SetLogLevel ¶
SetLogLevel configures the logrus log level based on the configuration. It sets the log level to DebugLevel if debug mode is enabled, otherwise to InfoLevel.
func SetProxy ¶
SetProxy configures the provided HTTP client with proxy settings from the configuration. It supports SOCKS5, HTTP, and HTTPS proxies. The function modifies the client's transport to route requests through the configured proxy server.
func StripThinkingConfigIfUnsupported ¶ added in v6.3.0
StripThinkingConfigIfUnsupported removes thinkingConfig from the request body when the target model does not advertise Thinking capability. It cleans both standard Gemini and Gemini CLI JSON envelopes. This acts as a final safety net in case upstream injected thinking for an unsupported model.
func ThinkingEffortToBudget ¶ added in v6.6.0
ThinkingEffortToBudget maps reasoning effort levels to approximate budgets, clamping the result to the model's supported range.
func ThinkingFromMetadata ¶ added in v6.6.0
ThinkingFromMetadata extracts thinking overrides from metadata produced by NormalizeThinkingModel. It accepts both the new generic keys and legacy Gemini-specific keys.
func Walk ¶
Walk recursively traverses a JSON structure to find all occurrences of a specific field. It builds paths to each occurrence and adds them to the provided paths slice.
Parameters:
- value: The gjson.Result object to traverse
- path: The current path in the JSON structure (empty string for root)
- field: The field name to search for
- paths: Pointer to a slice where found paths will be stored
The function works recursively, building dot-notation paths to each occurrence of the specified field throughout the JSON structure.
func WritablePath ¶ added in v6.2.23
func WritablePath() string
WritablePath returns the cleaned WRITABLE_PATH environment variable when it is set. It accepts both uppercase and lowercase variants for compatibility with existing conventions.
Types ¶
This section is empty.
Source Files