Documentation
¶
Index ¶
- Constants
- Variables
- func AccessTokenSHA256(auth *Auth) string
- func AntigravityCreditsRequested(ctx context.Context) bool
- func ApplyAuthPriorityMetadata(auth *Auth, metadata map[string]any)
- func ApplyAuthWeightMetadata(auth *Auth, metadata map[string]any) error
- func ApplyCustomHeadersFromMetadata(auth *Auth)
- func AuthGrantFingerprint(a *Auth) string
- func CanonicalCredentialMetadataKey(key string) string
- func CanonicalSessionID(headers http.Header, payload []byte, metadata map[string]any) string
- func ClearUnauthorizedModelStates(auth *Auth, now time.Time) []string
- func CodexAPIKeyModelIsCompat(cfg *internalconfig.Config, auth *Auth, model string) bool
- func CodexOuterNeedsRefresh(a *Auth, now time.Time) (dueAt time.Time, hasRefresh bool, needsRefresh bool)
- func CodexSIWCNeedsRefresh(a *Auth, now time.Time) (dueAt time.Time, hasRefresh bool, needsRefresh bool)
- func CredentialsChanged(existing, incoming *Auth) bool
- func ExtractCustomHeadersFromMetadata(metadata map[string]any) map[string]string
- func ExtractSessionID(headers http.Header, payload []byte, metadata map[string]any) string
- func ExtractUpstreamErrorSummary(raw string) string
- func HasAuthCreationIntent(ctx context.Context) bool
- func HasDisabledInvalidGrantFailure(auth *Auth) bool
- func HasKnownAntigravityCreditsHint(authID string) bool
- func HasTrustedRetryDeadline(err error) bool
- func HasUnauthorizedAuthFailure(auth *Auth) bool
- func IsAntigravityCreditsHintFresh(hint AntigravityCreditsHint, now time.Time) bool
- func IsAuthAvailableForModel(auth *Auth, model string, now time.Time) bool
- func IsAuthTokenPayloadKey(key string) bool
- func IsCodexAuthRecord(auth *Auth) bool
- func IsCodexClientRequest(ctx context.Context, clientHeaders ...http.Header) bool
- func IsCodexClientUserAgent(userAgent string) bool
- func IsCodexUseSIWC(a *Auth) bool
- func IsCodexUseSIWCForRequest(ctx context.Context, a *Auth, clientHeaders ...http.Header) bool
- func IsConfigAPIKeyAuth(auth *Auth) bool
- func IsForceRefreshContext(ctx context.Context) bool
- func IsPluginVirtualAuth(auth *Auth) bool
- func IsTerminalAuthError(err error) bool
- func MarkPluginVirtualAuth(auth *Auth, sourcePath string, ordinal int)
- func MatchRequestScopedErrorAction(auth *Auth, err error, cfg *internalconfig.Config) (string, bool)
- func MatchRequestScopedErrorRules(rules []internalconfig.RequestScopedErrorRule, err error) (string, bool)
- func MergeExistingAuthMetadata(target *Auth, existingMap map[string]any)
- func NewHomeConcurrencyBusyError(message string, retryAfter time.Duration) error
- func NewModelCooldownError(model, provider string, resetIn time.Duration) error
- func NewTerminalAuthError(err *Error, cause error) error
- func NormalizeCredentialMetadata(metadata map[string]any)
- func NotifyAccessTokenFingerprint(ctx context.Context, auth *Auth)
- func OAuthGrantFingerprint(accessToken, refreshToken, email, accountID string) string
- func OAuthModelAliasChannel(provider, authKind string) string
- func OAuthModelAliasesFromAttributes(attributes map[string]string) []internalconfig.OAuthModelAlias
- func PersistCodexAuthFile(ctx context.Context, path string, auth *Auth) (bool, error)
- func ProviderRefreshLead(provider string, runtime any) *time.Duration
- func ProviderSupportsQuotaObservation(provider string) bool
- func QuotaCooldownDisabledForAuth(auth *Auth) bool
- func QuotaCooldownDisabledForAuthWithConfig(auth *Auth, cfg *internalconfig.Config) bool
- func RegisterRefreshLeadProvider(provider string, factory func() *time.Duration)
- func RequestScopedErrorConfigFromContext(ctx context.Context) *internalconfig.Config
- func ResolveRequestScopedErrorRules(auth *Auth, cfg *internalconfig.Config) []internalconfig.RequestScopedErrorRule
- func ResolvedAPIKeyModelInfo(req cliproxyexecutor.Request) (*registry.ModelInfo, bool)
- func ResolvedHomeModelOptions(req cliproxyexecutor.Request) (internalconfig.OpenAICompatibilityModel, bool)
- func ResolvedModelInfo(req cliproxyexecutor.Request) (*registry.ModelInfo, bool)
- func SafeResponseHeaders(err error) http.Header
- func SanitizeRenewalMessage(raw string) string
- func SanitizeUpstreamErrorSummary(s string) string
- func SetAntigravityCreditsHint(authID string, hint AntigravityCreditsHint)
- func SetOAuthModelAliasesAttribute(auth *Auth, aliases []internalconfig.OAuthModelAlias)
- func SetQuotaCooldownDisabled(disable bool)
- func SetTransientErrorCooldownSeconds(seconds int)
- func ValidateAuthWeight(auth *Auth) error
- func WithAntigravityCredits(ctx context.Context) context.Context
- func WithAuthCreationIntent(ctx context.Context) context.Context
- func WithCause(err *Error, cause error) error
- func WithCodexClientRequest(ctx context.Context, isCodexClient bool) context.Context
- func WithDeferredAPIKeyModelAliasRebuild(ctx context.Context) context.Context
- func WithForceRefresh(ctx context.Context) context.Context
- func WithRequestInfo(ctx context.Context, info *RequestInfo) context.Context
- func WithRequestScopedErrorConfig(ctx context.Context, cfg *internalconfig.Config) context.Context
- func WithSkipPersist(ctx context.Context) context.Context
- func WithoutSkipPersist(ctx context.Context) context.Context
- type APIKeyConfigEntry
- type APIKeyConfigExecutor
- type AntigravityCreditsHint
- type ApplyPatchSupport
- type Auth
- func (a *Auth) AccessTokenExpirationTime() (time.Time, bool)
- func (a *Auth) AccessTokenExpirationTimeForRequest(ctx context.Context, clientHeaders ...http.Header) (time.Time, bool)
- func (a *Auth) AccountInfo() (string, string)
- func (a *Auth) AuthKind() string
- func (a *Auth) AuthSourceKind() string
- func (a *Auth) BindFileSnapshot(path string, data []byte)
- func (a *Auth) ClearFileSnapshot()
- func (a *Auth) Clone() *Auth
- func (a *Auth) CodexSIWCStatus(now time.Time) SIWCStatus
- func (a *Auth) DisableCoolingOverride() (bool, bool)
- func (a *Auth) EnsureIndex() string
- func (a *Auth) ExpirationTime() (time.Time, bool)
- func (a *Auth) FileSnapshotMatchesDisk() bool
- func (a *Auth) FileSnapshotPath() string
- func (a *Auth) HasFileSnapshot() bool
- func (a *Auth) HasValidAccessToken(now time.Time) bool
- func (a *Auth) InvalidateFileSnapshot()
- func (a *Auth) OuterAccessTokenExpirationTime() (time.Time, bool)
- func (a *Auth) OuterExpirationTime() (time.Time, bool)
- func (a *Auth) ProxyInfo() string
- func (a *Auth) RecentRequestsSnapshot(now time.Time) []RecentRequestBucket
- func (a *Auth) RecoveryStageAt(now time.Time) string
- func (a *Auth) RenewalStateAt(now time.Time) string
- func (a *Auth) RequestRetryOverride() (int, bool)
- func (a *Auth) SIWCEarliestRefreshTime() (time.Time, bool)
- func (a *Auth) SIWCExpirationTime() (time.Time, bool)
- func (a *Auth) SIWCRealExpirationTime() (time.Time, bool)
- func (a *Auth) SameFileSnapshot(other *Auth) bool
- func (a *Auth) ToolPrefixDisabled() bool
- type AuthExecutionSessionCloser
- type CooldownStateRecord
- type CooldownStateStore
- type CooldownStateStoreProvider
- type CooldownView
- type Error
- type ExecutionSessionCloser
- type ExecutionSessionSharer
- type FileCooldownStateStore
- type FillFirstSelector
- type ForceRefreshResult
- type HomeConcurrencyBusyError
- type HomeDispatchBundle
- type HomeDispatchSelection
- func (s *HomeDispatchSelection) Active() bool
- func (s *HomeDispatchSelection) AttemptContext(ctx context.Context) (context.Context, func(), error)
- func (s *HomeDispatchSelection) Bind(closeFn func() error) error
- func (s *HomeDispatchSelection) CloneAuth() *Auth
- func (s *HomeDispatchSelection) CloneAuthForRoute(routeModel string) *Auth
- func (s *HomeDispatchSelection) End(reason string)
- func (s *HomeDispatchSelection) EndWebsocketTurn(ctx context.Context, reason string)
- func (s *HomeDispatchSelection) EndWithRelease(reason string) *executionregistry.ReleaseTicket
- func (s *HomeDispatchSelection) ReplaceAuth(auth *Auth)
- func (s *HomeDispatchSelection) Retain()
- func (s *HomeDispatchSelection) Retained() bool
- type HomeInFlightPublisherConfig
- type HomeInFlightTransport
- type Hook
- type InFlightSnapshot
- type Manager
- func (m *Manager) ApplyConfigWithCooldownStateStore(ctx context.Context, cfg *internalconfig.Config, store CooldownStateStore) bool
- func (m *Manager) ApplyHomeInFlightPublisherConfig(cfg HomeInFlightPublisherConfig)
- func (m *Manager) ApplyRequestScopedErrorResult(ctx context.Context, auth *Auth, err error, result *Result) (string, bool)
- func (m *Manager) AvailableProviders() []string
- func (m *Manager) BindCodexSIWC(ctx context.Context, id string, expectedEpoch uint64, expectedAccount string, ...) (*Auth, error)
- func (m *Manager) ClearHomeDispatchBundle(bundle *HomeDispatchBundle) bool
- func (m *Manager) ClearHomeExecutionRegistry(registry *executionregistry.Registry) bool
- func (m *Manager) CloseExecutionSession(sessionID string)
- func (m *Manager) Execute(ctx context.Context, providers []string, req cliproxyexecutor.Request, ...) (cliproxyexecutor.Response, error)
- func (m *Manager) ExecuteCount(ctx context.Context, providers []string, req cliproxyexecutor.Request, ...) (cliproxyexecutor.Response, error)
- func (m *Manager) ExecuteStream(ctx context.Context, providers []string, req cliproxyexecutor.Request, ...) (result *cliproxyexecutor.StreamResult, err error)
- func (m *Manager) Executor(provider string) (ProviderExecutor, bool)
- func (m *Manager) ForceRefreshAll(ctx context.Context) []ForceRefreshResult
- func (m *Manager) ForceRefreshAuth(ctx context.Context, id string) (*Auth, error)
- func (m *Manager) GetByID(id string) (*Auth, bool)
- func (m *Manager) GetExecutionSessionAuthByID(sessionID string, authID string) (*Auth, bool)
- func (m *Manager) HasAlternativeTargetForModel(ctx context.Context, providers []string, model string, ...) bool
- func (m *Manager) HasProviderAuth(provider string) bool
- func (m *Manager) HomeDispatchBundle() *HomeDispatchBundle
- func (m *Manager) HomeEnabled() bool
- func (m *Manager) HomeExecutionRegistry() *executionregistry.Registry
- func (m *Manager) HomeInFlightPublisherConfig() HomeInFlightPublisherConfig
- func (m *Manager) HttpRequest(ctx context.Context, auth *Auth, req *http.Request) (*http.Response, error)
- func (m *Manager) InFlightSnapshot() InFlightSnapshot
- func (m *Manager) InjectCredentials(req *http.Request, authID string) error
- func (m *Manager) List() []*Auth
- func (m *Manager) Load(ctx context.Context) error
- func (m *Manager) LookupSessionAffinity(provider, model, sessionID string) (*Auth, string)
- func (m *Manager) MarkResult(ctx context.Context, result Result)
- func (m *Manager) MaxRetryCredentials() int
- func (m *Manager) Modify(ctx context.Context, id string, expectedEpoch uint64, edit func(*Auth) error) (*Auth, bool, error)
- func (m *Manager) NewHttpRequest(ctx context.Context, auth *Auth, method, targetURL string, body []byte, ...) (*http.Request, error)
- func (m *Manager) NextExecutionSeq() uint64
- func (m *Manager) PersistCooldownStates(ctx context.Context)
- func (m *Manager) PersistMetadataEntry(ctx context.Context, id string, expectedEpoch uint64, key string, value any, ...) (bool, bool)
- func (m *Manager) PluginSchedulerWantsAcrossPriorities() bool
- func (m *Manager) PrepareHttpRequest(ctx context.Context, auth *Auth, req *http.Request) error
- func (m *Manager) PrepareRequestAuth(ctx context.Context, preparer RequestAuthPreparer, auth *Auth) (*Auth, error)
- func (m *Manager) PublishHomeDispatch(client homeAuthDispatcher, registry *executionregistry.Registry, ...) *HomeDispatchBundle
- func (m *Manager) PublishIfRegistrationCurrent(id string, registrationEpoch uint64, prefix, provider string, disabled bool, ...) bool
- func (m *Manager) ReconcileRegistryModelStates(ctx context.Context, authID string)
- func (m *Manager) RefreshAPIKeyModelAlias()
- func (m *Manager) RefreshAfterUnauthorized(ctx context.Context, auth *Auth, execErr error, alreadyTried bool, ...) (*Auth, bool)
- func (m *Manager) RefreshHomeSelectionAfterUnauthorized(ctx context.Context, selection *HomeDispatchSelection, failedAuth *Auth) (*Auth, bool, error)
- func (m *Manager) RefreshSchedulerAll()
- func (m *Manager) RefreshSchedulerEntry(authID string)
- func (m *Manager) Register(ctx context.Context, auth *Auth) (*Auth, error)
- func (m *Manager) RegisterExecutor(executor ProviderExecutor)
- func (m *Manager) Remove(ctx context.Context, id string)
- func (m *Manager) RemoveIf(ctx context.Context, id string, predicate func(*Auth) bool) bool
- func (m *Manager) ReportHomeUnauthorized(ctx context.Context, auth *Auth, provider, model string, ...)
- func (m *Manager) ResetQuota(ctx context.Context, authID string) (*Auth, []string, error)
- func (m *Manager) ResolveExecutionModel(auth *Auth, routeModel string) string
- func (m *Manager) RestoreCooldownStates(ctx context.Context) error
- func (m *Manager) ResultPolicy() ResultPolicy
- func (m *Manager) SelectAuth(ctx context.Context, provider, model string, opts cliproxyexecutor.Options) (*Auth, error)
- func (m *Manager) SelectAuthByKind(ctx context.Context, provider, model, requiredKind string, ...) (*Auth, error)
- func (m *Manager) SelectAuthExcluding(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, ...) (*Auth, error)
- func (m *Manager) SelectAuthWithCredentialPolicy(ctx context.Context, provider, model, policy string, ...) (*Auth, error)
- func (m *Manager) SelectHomeAuthByKind(ctx context.Context, provider string, model string, requiredKind string, ...) (*HomeDispatchSelection, error)
- func (m *Manager) SelectHomeAuthWithCredentialPolicy(ctx context.Context, provider, model, policy string, ...) (*HomeDispatchSelection, error)
- func (m *Manager) Selector() Selector
- func (m *Manager) SetConfig(cfg *internalconfig.Config)
- func (m *Manager) SetConfigSnapshot(cfg *internalconfig.Config) bool
- func (m *Manager) SetCooldownStateStore(store CooldownStateStore)
- func (m *Manager) SetHomeExecutionRegistry(registry *executionregistry.Registry)
- func (m *Manager) SetOAuthModelAlias(aliases map[string][]internalconfig.OAuthModelAlias)
- func (m *Manager) SetPluginScheduler(scheduler PluginScheduler)
- func (m *Manager) SetResultPolicy(policy ResultPolicy)
- func (m *Manager) SetRetryConfig(retry int, maxRetryInterval time.Duration, maxRetryCredentials int)
- func (m *Manager) SetRoundTripperProvider(p RoundTripperProvider)
- func (m *Manager) SetSelector(selector Selector)
- func (m *Manager) SetStore(store Store)
- func (m *Manager) StartAutoRefresh(parent context.Context, interval time.Duration)
- func (m *Manager) StartHomeInFlightPublisher(ctx context.Context, transport HomeInFlightTransport, ...)
- func (m *Manager) StopAutoRefresh()
- func (m *Manager) SupportsApplyPatchForProviders(providers []string) bool
- func (m *Manager) SupportsNativeToolSearchForModel(model string) bool
- func (m *Manager) SwapCooldownStateStore(ctx context.Context, store CooldownStateStore, persistOld bool) bool
- func (m *Manager) UnregisterExecutor(provider string)
- func (m *Manager) Update(ctx context.Context, auth *Auth) (*Auth, error)
- func (m *Manager) UpdateIfRegistrationCurrent(ctx context.Context, base *Auth, updated *Auth) (*Auth, bool, error)
- func (m *Manager) UpdatePreparedAuth(ctx context.Context, base, updated *Auth) (*Auth, error)
- func (m *Manager) UpdateRefreshedAuth(ctx context.Context, base, updated *Auth) (*Auth, error)
- func (m *Manager) VerifyInference(ctx context.Context, id, model string) (*Auth, error)
- func (m *Manager) WatchAuthChanges(authID string) (<-chan struct{}, func())
- type ModelState
- type NativeToolSearchSupport
- type NoopHook
- type OAuthModelAliasResult
- type PluginScheduler
- type PluginSchedulerAcrossPriorities
- type PostAuthHook
- type ProviderExecutor
- type ProxyConnectionPoolOverride
- type QuotaState
- type RecentRequestBucket
- type RefreshEvaluator
- type RequestAuthPreparer
- type RequestInfo
- type RequestPreparer
- type Result
- type ResultPolicy
- type ResultPolicyFunc
- type RoundRobinSelector
- type RoundTripperProvider
- type SIWCStatus
- type Selector
- type SessionAffinityConfig
- type SessionAffinitySelector
- func (s *SessionAffinitySelector) ForgetAuth(authID string)
- func (s *SessionAffinitySelector) ForgetAuthUpTo(authID string, maxEpoch, maxGen uint64)
- func (s *SessionAffinitySelector) InvalidateAuth(authID string)
- func (s *SessionAffinitySelector) LookupAffinity(provider, model, sessionID string, authFilters ...func(authID string) bool) (string, string)
- func (s *SessionAffinitySelector) OnResult(res Result)
- func (s *SessionAffinitySelector) Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, ...) (selected *Auth, errPick error)
- func (s *SessionAffinitySelector) Stop()
- func (s *SessionAffinitySelector) Trees() *cliproxysession.InMemorySessionTreeStore
- type SessionCache
- func (c *SessionCache) CompareAndDelete(sessionID, expectedAuthID string) bool
- func (c *SessionCache) Get(sessionID string) (string, bool)
- func (c *SessionCache) GetAndRefresh(sessionID string) (string, bool)
- func (c *SessionCache) Invalidate(sessionID string)
- func (c *SessionCache) InvalidateAuth(authID string)
- func (c *SessionCache) Len() int
- func (c *SessionCache) Set(sessionID, authID string)
- func (c *SessionCache) SetAliases(authID string, sessionIDs ...string)
- func (c *SessionCache) Stop()
- func (c *SessionCache) Touch(sessionID, expectedAuthID string) bool
- type Status
- type StoppableSelector
- type Store
- type StreamRewriteOptions
- type StreamRewriter
- type WeightedRoundRobinSelector
Constants ¶
const ( AuthKindAPIKey = "apikey" AuthKindOAuth = "oauth" AuthSourceConfig = "config" AuthSourceFile = "file" AuthSourceGit = "git" AuthSourceMemory = "memory" AuthSourceObjectStore = "objectstore" AuthSourcePostgres = "postgres" AttributeAPIKey = "api_key" AttributeAuthKind = "auth_kind" AttributeCodexAlphaSearch = "codex_alpha_search" AttributeCodexDisableCloaking = "codex_disable_cloaking" AttributeConfigIndex = "config_index" AttributePath = "path" AttributeRuntimeOnly = "runtime_only" AttributeSource = "source" AttributeSourceBackend = "source_backend" AttributeWeight = "weight" )
const ( // ExcludedAuthIDsMetadataKey stores credential IDs already attempted in the // current request retry round. ExcludedAuthIDsMetadataKey = "excluded_auth_ids" // CloseAllExecutionSessionsID asks an executor to release all active execution sessions. // Executors that do not support this marker may ignore it. CloseAllExecutionSessionsID = "__all_execution_sessions__" )
const ( RequestScopedActionStop = "stop" RequestScopedActionStopAndCooldown = "stop-and-cooldown" RequestScopedActionContinue = "continue" RequestScopedActionContinueAndCooldown = "continue-and-cooldown" )
Request-scoped error actions.
const ( // SessionAffinityRebindOnAny rebinds the session on any credential-attributed failure (default). SessionAffinityRebindOnAny = "any" // SessionAffinityRebindOnQuota preserves the existing session binding across transient failures // and only rebinds on quota, auth, model-support, or permanent unavailability. SessionAffinityRebindOnQuota = "quota" // SessionAffinityRebindOnNever preserves the existing session binding across all failures // and refuses to fail over a bound session to another credential. SessionAffinityRebindOnNever = "never" )
const ( AttributeAuthIndexSeed = "auth_index_seed" AttributePluginVirtual = "plugin_virtual" AttributeVirtualSource = "virtual_source" )
const ( RenewalStateSignInRequired = "sign_in_required" RenewalStateExpiredSignInRequired = "expired_sign_in_required" RenewalStateRetryScheduled = "retry_scheduled" RenewalStateRenewalVerified = "renewal_verified" RenewalStateAwaitingFirstRenewal = "awaiting_first_renewal" RecoveryStageSignInRequired = "sign_in_required" RecoveryStageCredentialSaved = "credential_saved" RecoveryStageQuotaBlocked = "quota_blocked" RecoveryStageRenewalVerified = "renewal_verified" RecoveryStageInferenceVerified = "inference_verified" RecoveryStageLoaded = "loaded" )
const AntigravityCreditsHintRefreshInterval = 10 * time.Minute
AntigravityCreditsHintRefreshInterval defines how long a cached AI credits hint remains fresh before it should be re-validated.
const AttributeFilePriority = "file_priority"
AttributeFilePriority marks priority values inherited from a physical auth file.
const CodexOuterRefreshLead = 96 * time.Hour
CodexOuterRefreshLead is the conservative proactive refresh lead time before the nominal 10-day Codex OAuth JWT expiration, refreshing tokens well ahead of early upstream access-token invalidation.
const CodexSIWCRefreshLead = 5 * time.Minute
CodexSIWCRefreshLead is the minimum remaining validity required before refreshing a Sign in with ChatGPT (SIWC) token, matching pi's DEFAULT_OAUTH_MINIMUM_VALIDITY_MS (5 minutes).
const (
// CredentialPolicyCodexAlphaSearchV1 selects credentials supported by Codex Alpha Search.
CredentialPolicyCodexAlphaSearchV1 = "codex_alpha_search_v1"
)
const ErrorCodeConnectionLifecycle = "connection_lifecycle"
ErrorCodeConnectionLifecycle marks transport/session lifecycle failures that must skip credential cooldown without being treated as request-scoped faults.
const ErrorCodeCredentialQuota = "credential_quota"
ErrorCodeCredentialQuota marks a rate-limit/quota refusal that applies to the entire credential across all models rather than only the reporting model.
const ErrorCodeForceCooldown = "force_cooldown"
ErrorCodeForceCooldown marks failures that must enforce credential cooldown.
const ErrorCodeRequestScoped = "request_scoped"
ErrorCodeRequestScoped identifies failures tied to the current request rather than the selected credential.
const ErrorCodeStreamTruncated = "stream_truncated"
ErrorCodeStreamTruncated marks locally synthesized failures for accepted upstream streams that ended without a terminal frame. The public status stays 502, but the credential must not cool and the generation must not be replayed on another credential.
const ErrorCodeTransientRateLimit = "transient_rate_limit"
ErrorCodeTransientRateLimit marks a transient per-model capacity or admission 429 (for example a Codex turn_rate_limit_exceeded rejection). The public status stays 429, but the credential quota is not exhausted: only the reporting model cools until the provider retry hint, without quota labelling or quota exponential backoff.
const ErrorCodeTransientTransport = "transient_transport"
ErrorCodeTransientTransport marks pre-HTTP dial/TLS/DNS/reset failures that must skip credential cooldown and remain eligible for request-retry rounds.
Variables ¶
var ErrMalformedHomeConcurrencyTuple = errors.New("malformed Home concurrency tuple")
Functions ¶
func AccessTokenSHA256 ¶
AccessTokenSHA256 returns the normalized OAuth access-token fingerprint used to fence asynchronous Home execution results without exposing the token.
func AntigravityCreditsRequested ¶
AntigravityCreditsRequested reports whether the context carries the credits flag.
func ApplyAuthPriorityMetadata ¶
ApplyAuthPriorityMetadata copies a valid file priority into an auth's metadata and routing attributes.
func ApplyAuthWeightMetadata ¶
ApplyAuthWeightMetadata validates the auth and applies a source metadata weight.
func ApplyCustomHeadersFromMetadata ¶
func ApplyCustomHeadersFromMetadata(auth *Auth)
func AuthGrantFingerprint ¶ added in v8.0.48
AuthGrantFingerprint computes a SHA-256 fingerprint of the credential's token grant and account identity.
func CanonicalCredentialMetadataKey ¶
CanonicalCredentialMetadataKey returns the canonical snake_case name for credential metadata keys that previously also accepted config-style aliases.
func CanonicalSessionID ¶
CanonicalSessionID resolves the single authoritative session identity from request options and metadata.
func ClearUnauthorizedModelStates ¶
ClearUnauthorizedModelStates resets model states whose last error was an unauthorized failure.
func CodexAPIKeyModelIsCompat ¶
func CodexAPIKeyModelIsCompat(cfg *internalconfig.Config, auth *Auth, model string) bool
CodexAPIKeyModelIsCompat reports whether the selected codex-api-key model has is-compat enabled. When true, Codex MultiAgentV2 agent_message items are converted into portable Responses message/user input for third-party Responses-compatible endpoints.
func CodexOuterNeedsRefresh ¶ added in v8.0.25
func CodexOuterNeedsRefresh(a *Auth, now time.Time) (dueAt time.Time, hasRefresh bool, needsRefresh bool)
CodexOuterNeedsRefresh evaluates the outer credential refresh due time and whether it needs refresh at now.
func CodexSIWCNeedsRefresh ¶ added in v8.0.25
func CodexSIWCNeedsRefresh(a *Auth, now time.Time) (dueAt time.Time, hasRefresh bool, needsRefresh bool)
CodexSIWCNeedsRefresh evaluates the nested "siwc" credential section refresh due time and whether it needs refresh at now.
func CredentialsChanged ¶
CredentialsChanged reports whether authentication credentials (tokens or API keys) differ between two Auth records.
func ExtractSessionID ¶
ExtractSessionID extracts a session identifier from explicit client signals, then falls back to execution metadata, derived identity, and message history. Priority order:
- X-Claude-Code-Session-Id
- Claude Code metadata.user_id session
- Session-Id / Session_id (Codex and compatible clients)
- X-Session-ID
- X-Session-Affinity (OpenCode)
- X-Client-Request-Id (pi Responses)
- session_id / sessionId
- prompt_cache_key, with conversation / conversation.id as an alias
- metadata.user_id and conversation_id legacy body fields
- explicit execution session metadata
- stable context-derived session identity
- stable hash from initial message content
func ExtractUpstreamErrorSummary ¶
ExtractUpstreamErrorSummary extracts and sanitizes a concise error summary from upstream error strings.
func HasAuthCreationIntent ¶
HasAuthCreationIntent reports whether the current save is part of a login or credential migration flow that may intentionally create a disabled record.
func HasDisabledInvalidGrantFailure ¶
HasDisabledInvalidGrantFailure reports whether the auth is disabled and has encountered an invalid_grant error.
func HasKnownAntigravityCreditsHint ¶
HasKnownAntigravityCreditsHint reports whether credits state has been discovered for an auth.
func HasTrustedRetryDeadline ¶ added in v8.0.45
HasTrustedRetryDeadline reports whether err carries a locally trusted recovery deadline, even after that deadline has passed. Header writers use it to keep a stale raw upstream Retry-After from resurfacing.
func HasUnauthorizedAuthFailure ¶
HasUnauthorizedAuthFailure reports whether the auth has a terminal unauthorized error with no pending refresh scheduled.
func IsAntigravityCreditsHintFresh ¶ added in v8.0.34
func IsAntigravityCreditsHintFresh(hint AntigravityCreditsHint, now time.Time) bool
IsAntigravityCreditsHintFresh reports whether a known credits hint is still within AntigravityCreditsHintRefreshInterval of now.
func IsAuthAvailableForModel ¶ added in v8.0.56
IsAuthAvailableForModel reports whether auth is eligible for selection on model at now.
func IsAuthTokenPayloadKey ¶
IsAuthTokenPayloadKey returns true if key is a credential or token lifecycle field that should not overwrite newly acquired OAuth credentials during metadata merge.
func IsCodexAuthRecord ¶ added in v8.0.25
IsCodexAuthRecord reports whether auth represents a Codex credential record.
func IsCodexClientRequest ¶ added in v8.0.40
IsCodexClientRequest reports whether the request originates from a Codex client.
func IsCodexClientUserAgent ¶ added in v8.0.40
IsCodexClientUserAgent reports whether userAgent identifies a Codex client.
func IsCodexUseSIWC ¶ added in v8.0.25
IsCodexUseSIWC reports whether a Codex auth record is configured to use its nested "siwc" section.
func IsCodexUseSIWCForRequest ¶ added in v8.0.40
IsCodexUseSIWCForRequest reports whether a request should use the nested SIWC credential section. Requests from Codex clients ignore use_siwc and always use non-SIWC credentials.
func IsConfigAPIKeyAuth ¶
IsConfigAPIKeyAuth reports whether the auth entry is synthesized from config *-api-key lists.
func IsForceRefreshContext ¶ added in v8.0.25
IsForceRefreshContext reports whether ctx carries an explicit forced credential refresh marker.
func IsPluginVirtualAuth ¶
IsPluginVirtualAuth reports whether an auth was expanded from a plugin-owned source file.
func IsTerminalAuthError ¶
IsTerminalAuthError checks if err or any error in its chain represents a permanent upstream auth failure.
func MarkPluginVirtualAuth ¶
MarkPluginVirtualAuth marks an auth that was expanded from a plugin-owned source file.
func MatchRequestScopedErrorAction ¶ added in v8.0.64
func MatchRequestScopedErrorAction(auth *Auth, err error, cfg *internalconfig.Config) (string, bool)
MatchRequestScopedErrorAction evaluates an error against the auth's RequestScopedErrors rules. If a rule matches, it returns (action, true). If no rule matches, it returns ("", false).
func MatchRequestScopedErrorRules ¶ added in v8.0.64
func MatchRequestScopedErrorRules(rules []internalconfig.RequestScopedErrorRule, err error) (string, bool)
MatchRequestScopedErrorRules evaluates an error against a pre-resolved rule list.
func MergeExistingAuthMetadata ¶
MergeExistingAuthMetadata merges user-configured metadata fields from existingMap into target.Metadata and target.Storage if target does not already define them.
func NewHomeConcurrencyBusyError ¶
NewHomeConcurrencyBusyError creates a typed Home concurrency busy error.
func NewModelCooldownError ¶
NewModelCooldownError creates an error representing model-level cooldown.
func NewTerminalAuthError ¶
NewTerminalAuthError wraps an *Error and cause as a terminal upstream authentication failure.
func NormalizeCredentialMetadata ¶
NormalizeCredentialMetadata rewrites recognized legacy keys to their canonical snake_case names. An explicitly present canonical value wins.
func NotifyAccessTokenFingerprint ¶
NotifyAccessTokenFingerprint reports the auth snapshot actually used by an executor that may refresh its local token before sending upstream. The observer derives the fingerprint and can reuse that snapshot for recovery.
func OAuthGrantFingerprint ¶ added in v8.0.48
OAuthGrantFingerprint computes a SHA-256 fingerprint of an OAuth grant's tokens and account identity.
func OAuthModelAliasChannel ¶
OAuthModelAliasChannel returns the OAuth model alias channel name for a given provider and auth kind. Returns empty string if the provider/authKind combination doesn't support OAuth model alias (e.g., API key authentication).
Built-in channels: vertex, aistudio, antigravity, claude, codex, kimi, xai, meta. Plugin OAuth providers use their normalized provider key as the channel.
func OAuthModelAliasesFromAttributes ¶
func OAuthModelAliasesFromAttributes(attributes map[string]string) []internalconfig.OAuthModelAlias
OAuthModelAliasesFromAttributes returns sanitized per-auth OAuth model aliases from auth attributes.
func PersistCodexAuthFile ¶ added in v8.0.25
PersistCodexAuthFile persists a Codex auth record to path using inter-process file locking, read-before-write merging, and scoped refresh patches when present. It returns handled=false when auth is not a Codex credential record.
func ProviderSupportsQuotaObservation ¶
ProviderSupportsQuotaObservation reports whether the named provider emits a passive credential-level quota snapshot understood by collectQuotaSignals.
func QuotaCooldownDisabledForAuth ¶
QuotaCooldownDisabledForAuth returns whether cooling is disabled for the auth under global settings.
func QuotaCooldownDisabledForAuthWithConfig ¶
func QuotaCooldownDisabledForAuthWithConfig(auth *Auth, cfg *internalconfig.Config) bool
QuotaCooldownDisabledForAuthWithConfig returns whether cooling is disabled for the auth with the given config.
func RequestScopedErrorConfigFromContext ¶ added in v8.0.64
func RequestScopedErrorConfigFromContext(ctx context.Context) *internalconfig.Config
RequestScopedErrorConfigFromContext retrieves the runtime config snapshot stored by WithRequestScopedErrorConfig.
func ResolveRequestScopedErrorRules ¶ added in v8.0.64
func ResolveRequestScopedErrorRules(auth *Auth, cfg *internalconfig.Config) []internalconfig.RequestScopedErrorRule
ResolveRequestScopedErrorRules extracts and deep-copies the effective RequestScopedErrorRule list for an auth and config snapshot.
func ResolvedAPIKeyModelInfo ¶
func ResolvedAPIKeyModelInfo(req cliproxyexecutor.Request) (*registry.ModelInfo, bool)
ResolvedAPIKeyModelInfo returns the exact configured model definition bound to this API-key execution attempt.
func ResolvedHomeModelOptions ¶ added in v8.0.4
func ResolvedHomeModelOptions(req cliproxyexecutor.Request) (internalconfig.OpenAICompatibilityModel, bool)
ResolvedHomeModelOptions returns the credential model options selected for this attempt. A present but unmatched or empty models list yields zero-value options.
func ResolvedModelInfo ¶
func ResolvedModelInfo(req cliproxyexecutor.Request) (*registry.ModelInfo, bool)
ResolvedModelInfo returns the authoritative model capabilities bound to this execution attempt.
func SafeResponseHeaders ¶
SafeResponseHeaders returns trusted response headers only for concrete retry/cooldown errors.
func SanitizeRenewalMessage ¶ added in v8.0.48
SanitizeRenewalMessage strips URLs, bearer tokens, JWTs, OAuth codes/states, and secret fields from diagnostic messages.
func SanitizeUpstreamErrorSummary ¶
SanitizeUpstreamErrorSummary removes sensitive credentials, tokens, and paths, and bounds length.
func SetAntigravityCreditsHint ¶
func SetAntigravityCreditsHint(authID string, hint AntigravityCreditsHint)
SetAntigravityCreditsHint updates the latest known AI credits state for an auth.
func SetOAuthModelAliasesAttribute ¶
func SetOAuthModelAliasesAttribute(auth *Auth, aliases []internalconfig.OAuthModelAlias)
SetOAuthModelAliasesAttribute stores sanitized per-auth OAuth model aliases on an auth entry.
func SetQuotaCooldownDisabled ¶
func SetQuotaCooldownDisabled(disable bool)
SetQuotaCooldownDisabled toggles auth/model cooldown scheduling globally.
func SetTransientErrorCooldownSeconds ¶
func SetTransientErrorCooldownSeconds(seconds int)
SetTransientErrorCooldownSeconds configures cooldowns for 408/500/502/503/504. 0 keeps the legacy default; negative values disable transient error cooldowns.
func ValidateAuthWeight ¶
ValidateAuthWeight validates every explicit credential weight source.
func WithAntigravityCredits ¶
WithAntigravityCredits returns a child context that signals the executor to inject enabledCreditTypes into the request payload.
func WithAuthCreationIntent ¶
WithAuthCreationIntent returns a derived context that allows a token store to create a missing disabled credential. It is intended only for the immediate persistence performed by login and credential migration flows.
func WithCause ¶
WithCause wraps an *Error with an underlying cause without changing the Error struct layout.
func WithCodexClientRequest ¶ added in v8.0.45
WithCodexClientRequest stores the resolved Codex client detection flag in ctx so asynchronous post-request paths do not read a reused gin.Context.
func WithDeferredAPIKeyModelAliasRebuild ¶
WithDeferredAPIKeyModelAliasRebuild returns a derived context that defers API-key model alias table rebuilds. Callers that use this for a batch of Register/Update/Remove operations must call RefreshAPIKeyModelAlias once.
func WithForceRefresh ¶ added in v8.0.25
WithForceRefresh marks ctx as an explicit forced credential refresh.
func WithRequestInfo ¶
func WithRequestInfo(ctx context.Context, info *RequestInfo) context.Context
WithRequestInfo returns a new context with the given RequestInfo attached.
func WithRequestScopedErrorConfig ¶ added in v8.0.64
WithRequestScopedErrorConfig stores the runtime config snapshot on ctx so usage reporters can evaluate request-scoped error rules when publishing attempt failures.
func WithSkipPersist ¶
WithSkipPersist returns a derived context that disables persistence for Manager Update/Register calls. It is intended for code paths that are reacting to file watcher events, where the file on disk is already the source of truth and persisting again would create a write-back loop.
Types ¶
type APIKeyConfigEntry ¶
type APIKeyConfigEntry interface {
GetAPIKey() string
GetBaseURL() string
GetPrefix() string
GetProxyURL() string
}
APIKeyConfigEntry is a generic interface for API key configurations.
type APIKeyConfigExecutor ¶
type APIKeyConfigExecutor interface {
ForAPIKey() ProviderExecutor
}
APIKeyConfigExecutor provides an execution-local view without OAuth-only configuration. The registered executor and its shared session state stay intact.
type AntigravityCreditsHint ¶
type AntigravityCreditsHint struct {
Known bool
Available bool
CreditAmount float64
MinCreditAmount float64
PaidTierID string
UpdatedAt time.Time
}
AntigravityCreditsHint stores the latest known AI credits state for one auth.
func GetAntigravityCreditsHint ¶
func GetAntigravityCreditsHint(authID string) (AntigravityCreditsHint, bool)
GetAntigravityCreditsHint returns the latest known AI credits state for an auth.
func GetAntigravityCreditsHintRequired ¶
func GetAntigravityCreditsHintRequired(ctx context.Context, authID string) (AntigravityCreditsHint, bool, error)
GetAntigravityCreditsHintRequired returns the latest known AI credits state for request-time paths.
type ApplyPatchSupport ¶ added in v8.0.9
type ApplyPatchSupport interface {
SupportsApplyPatch() bool
}
ApplyPatchSupport optionally advertises the actual executor's tool contract. It does not change ProviderExecutor or the plugin ABI.
type Auth ¶
type Auth struct {
// ID uniquely identifies the auth record across restarts.
ID string `json:"id"`
// RegistrationEpoch tracks monotonic registration cycles across unregister/re-register.
RegistrationEpoch uint64 `json:"registration_epoch,omitempty"`
// CredentialVersion tracks monotonic credential replacements for secret material.
CredentialVersion uint64 `json:"credential_version,omitempty"`
// Generation tracks monotonic mutations to resolve scheduler/reconcile snapshot races.
Generation uint64 `json:"generation,omitempty"`
// Index is a stable runtime identifier derived from auth metadata (not persisted).
Index string `json:"-"`
// Provider is the upstream provider key (e.g. "gemini", "claude").
Provider string `json:"provider"`
// Prefix optionally namespaces models for routing (e.g., "teamA/gemini-3-pro-preview").
Prefix string `json:"prefix,omitempty"`
// FileName stores the relative or absolute path of the backing auth file.
FileName string `json:"-"`
// Storage holds the token persistence implementation used during login flows.
Storage baseauth.TokenStorage `json:"-"`
// CodexRefreshPatch carries an immutable pending credential update, never configuration.
CodexRefreshPatch *codex.CredentialRefreshPatch `json:"-"`
// Label is an optional human readable label for logging.
Label string `json:"label,omitempty"`
// Status is the lifecycle status managed by the AuthManager.
Status Status `json:"status"`
// StatusMessage holds a short description for the current status.
StatusMessage string `json:"status_message,omitempty"`
// Disabled indicates the auth is intentionally disabled by operator.
Disabled bool `json:"disabled"`
Unavailable bool `json:"unavailable"`
// ProxyURL overrides the global proxy setting for this auth if provided.
ProxyURL string `json:"proxy_url,omitempty"`
// ProxyConnectionPool carries the connection-pool block of this api-key
// credential. Nil means no pooling, which is the default. Pools are per
// credential, so an override here never shares connections with another auth.
ProxyConnectionPool *ProxyConnectionPoolOverride `json:"proxy_connection_pool,omitempty"`
// Attributes stores provider specific metadata needed by executors (immutable configuration).
Attributes map[string]string `json:"attributes,omitempty"`
// Metadata stores runtime mutable provider state (e.g. tokens, cookies).
Metadata map[string]any `json:"metadata,omitempty"`
// Quota captures recent quota information for load balancers.
Quota QuotaState `json:"quota"`
// LastError stores the last failure encountered while executing or refreshing.
LastError *Error `json:"last_error,omitempty"`
// CreatedAt is the creation timestamp in UTC.
CreatedAt time.Time `json:"created_at"`
// UpdatedAt is the last modification timestamp in UTC.
UpdatedAt time.Time `json:"updated_at"`
// LastRefreshedAt records the last successful refresh time in UTC.
LastRefreshedAt time.Time `json:"last_refreshed_at"`
// NextRefreshAfter is the earliest time a refresh should retrigger.
NextRefreshAfter time.Time `json:"next_refresh_after"`
// RefreshFailures tracks consecutive refresh failures for exponential backoff (in-memory only).
RefreshFailures int `json:"-"`
// NextRetryAfter is the earliest time a retry should retrigger.
NextRetryAfter time.Time `json:"next_retry_after"`
// ModelStates tracks per-model runtime availability data.
ModelStates map[string]*ModelState `json:"model_states,omitempty"`
// Runtime carries non-serialisable data used during execution (in-memory only).
Runtime any `json:"-"`
// RejectedAccessToken tracks the access token rejected by upstream 401 until a refresh succeeds.
RejectedAccessToken string `json:"-"`
// RejectedSIWCAccessToken tracks the nested SIWC access token rejected by upstream 401 until replaced.
RejectedSIWCAccessToken string `json:"-"`
// RejectedRefreshToken tracks the outer refresh token rejected as terminal until replaced.
RejectedRefreshToken string `json:"-"`
// RejectedSIWCRefreshToken tracks the nested SIWC refresh token rejected as terminal until replaced.
RejectedSIWCRefreshToken string `json:"-"`
// RenewalWarnedRefreshToken tracks the rejected refresh token that already emitted a terminal warning/event.
RenewalWarnedRefreshToken string `json:"-"`
// RequiresSignIn flags that automatic credential renewal failed with a terminal grant rejection.
RequiresSignIn bool `json:"-"`
// RefreshError stores the sanitized last refresh failure without being overwritten by request execution results.
RefreshError *Error `json:"-"`
// RenewalEventAt records when the deduplicated terminal renewal failure event was first observed for the current grant.
RenewalEventAt time.Time `json:"-"`
// AdoptedAt records when the current credential version was adopted into runtime state.
AdoptedAt time.Time `json:"-"`
// AdoptedGrantHash records the fingerprint of the credential grant when it was adopted into runtime state,
// preserved across upstream automatic refresh rotations and reset when the credential grant is externally replaced.
AdoptedGrantHash string `json:"-"`
// InferenceVerified reports whether the current credential version completed a real inference response.
InferenceVerified bool `json:"-"`
// LastInferenceVerifiedAt records when the current credential version last completed an inference response.
LastInferenceVerifiedAt time.Time `json:"-"`
// RenewalVerified reports whether the current credential version completed an automatic/proactive refresh cycle.
RenewalVerified bool `json:"-"`
// LastRenewalVerifiedAt records when the current credential version last completed a token refresh.
LastRenewalVerifiedAt time.Time `json:"-"`
Success int64 `json:"-"`
Failed int64 `json:"-"`
// contains filtered or unexported fields
}
Auth encapsulates the runtime state and metadata associated with a single credential.
func MergePreparedAuth ¶
MergePreparedAuth merges prepared request auth updates into current without modifying refresh lifecycle fields (such as LastRefreshedAt, LastError, or cooldown status).
func MergeRefreshedAuth ¶
MergeRefreshedAuth merges the refresh results from updated (derived from base) into the latest runtime auth current, preserving concurrent user modifications and active cooldowns.
func (*Auth) AccessTokenExpirationTime ¶
AccessTokenExpirationTime returns the expiration time of the specific access_token. If the access_token is a JWT, its exp claim takes strict precedence.
func (*Auth) AccessTokenExpirationTimeForRequest ¶ added in v8.0.56
func (a *Auth) AccessTokenExpirationTimeForRequest(ctx context.Context, clientHeaders ...http.Header) (time.Time, bool)
AccessTokenExpirationTimeForRequest returns the expiration time of the access_token selected for the request context and client headers.
func (*Auth) AccountInfo ¶
func (*Auth) AuthKind ¶
AuthKind returns the credential kind using explicit metadata first and legacy field-shape fallbacks second.
func (*Auth) AuthSourceKind ¶
AuthSourceKind returns where the Auth entry came from at runtime.
func (*Auth) BindFileSnapshot ¶ added in v8.0.33
BindFileSnapshot binds an unversioned file-synthesized Auth snapshot to the source file path and canonical SHA-256 digest of the bytes from which it was parsed.
func (*Auth) ClearFileSnapshot ¶ added in v8.0.33
func (a *Auth) ClearFileSnapshot()
ClearFileSnapshot removes any unversioned file-observation binding once the Auth is committed to runtime state or normalized for comparison.
func (*Auth) Clone ¶
Clone shallow copies the Auth structure, duplicating maps to avoid accidental mutation.
func (*Auth) CodexSIWCStatus ¶ added in v8.0.37
func (a *Auth) CodexSIWCStatus(now time.Time) SIWCStatus
CodexSIWCStatus evaluates the local SIWC credential status ("off", "valid", or "invalid") at the given time without triggering any refresh or upstream request.
func (*Auth) DisableCoolingOverride ¶
DisableCoolingOverride returns the auth-scoped disable_cooling override when present. The value is read from metadata key "disable_cooling" (or legacy "disable-cooling"). The second return value distinguishes explicit false from an absent override.
func (*Auth) EnsureIndex ¶
EnsureIndex returns a stable index derived from the auth file name or credential identity.
func (*Auth) ExpirationTime ¶
ExpirationTime attempts to extract the active credential expiration timestamp from metadata. When use_siwc is enabled on a Codex credential, the active SIWC section expiration is returned.
func (*Auth) FileSnapshotMatchesDisk ¶ added in v8.0.33
FileSnapshotMatchesDisk reports whether the backing file on disk still exists, is readable, and matches the canonical digest observed when this snapshot was synthesized.
func (*Auth) FileSnapshotPath ¶ added in v8.0.39
FileSnapshotPath returns the backing file path bound to this file snapshot.
func (*Auth) HasFileSnapshot ¶ added in v8.0.33
HasFileSnapshot reports whether this Auth is an unversioned file-synthesized snapshot bound to a specific file observation digest.
func (*Auth) HasValidAccessToken ¶
HasValidAccessToken returns whether the auth has a non-empty access token that is unexpired at the given time.
func (*Auth) InvalidateFileSnapshot ¶ added in v8.0.39
func (a *Auth) InvalidateFileSnapshot()
InvalidateFileSnapshot marks an unversioned file snapshot as discarded so a subsequent re-read of identical or reformatted file content is not suppressed.
func (*Auth) OuterAccessTokenExpirationTime ¶ added in v8.0.56
OuterAccessTokenExpirationTime returns the expiration time of the outer access_token, ignoring the nested "siwc" section.
func (*Auth) OuterExpirationTime ¶ added in v8.0.25
OuterExpirationTime extracts the outer credential expiration timestamp, ignoring the nested "siwc" section.
func (*Auth) RecentRequestsSnapshot ¶
func (a *Auth) RecentRequestsSnapshot(now time.Time) []RecentRequestBucket
func (*Auth) RecoveryStageAt ¶ added in v8.0.48
RecoveryStageAt returns the structured post-login / runtime adoption and verification stage at the given time.
func (*Auth) RenewalStateAt ¶ added in v8.0.48
RenewalStateAt returns the structured renewal lifecycle state at the given time.
func (*Auth) RequestRetryOverride ¶
RequestRetryOverride returns the auth-scoped request_retry override when present. The value is read from metadata key "request_retry" (or legacy "request-retry"). A negative value is treated as unset and falls back to the global request-retry.
func (*Auth) SIWCEarliestRefreshTime ¶ added in v8.0.61
SIWCEarliestRefreshTime returns the server's lower bound for SIWC token renewal.
func (*Auth) SIWCExpirationTime ¶ added in v8.0.25
SIWCExpirationTime extracts the expiration timestamp from the nested "siwc" metadata section.
func (*Auth) SIWCRealExpirationTime ¶ added in v8.0.37
SIWCRealExpirationTime extracts the real (unbuffered) expiration timestamp for the nested "siwc" access token. It reads "expires_at" (saved from OAuth expires_in) or the JWT "exp" claim of "access_token", without using the margin-deducted "expired" field.
func (*Auth) SameFileSnapshot ¶ added in v8.0.33
SameFileSnapshot reports whether two unversioned file snapshots observed the same canonical file content.
func (*Auth) ToolPrefixDisabled ¶
ToolPrefixDisabled returns whether the proxy_ tool name prefix should be skipped for this auth. When true, tool names are sent to Anthropic unchanged. The value is read from metadata key "tool_prefix_disabled" (or "tool-prefix-disabled").
type AuthExecutionSessionCloser ¶ added in v8.0.26
type AuthExecutionSessionCloser interface {
CloseAuthExecutionSessions(authID string)
}
AuthExecutionSessionCloser allows executors to release execution sessions associated with a removed credential without tearing down other credentials' sessions.
type CooldownStateRecord ¶
type CooldownStateRecord struct {
Provider string `json:"provider,omitempty"`
AuthID string `json:"auth_id"`
AuthFile string `json:"-"`
Model string `json:"model,omitempty"`
Status string `json:"status,omitempty"`
NextRetryAfter time.Time `json:"next_retry_after"`
Reason string `json:"reason,omitempty"`
Quota QuotaState `json:"quota,omitempty"`
LastError *Error `json:"last_error,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
// IndependentState preserves a model's own cooldown beneath an
// auth-level credential-quota layer so a restart cannot lose the
// distinction and quota restoration keeps reinstate-exactly semantics.
IndependentState *ModelState `json:"independent_state,omitempty"`
// CredentialQuotaPropagated preserves wrap provenance for models that
// carry no independent layer (e.g. the reporting model itself).
CredentialQuotaPropagated bool `json:"credential_quota_propagated,omitempty"`
// CooldownSignals persists bounded rejected quota headers captured when
// this cooldown was recorded without touching passive Quota.Signals watermarks.
CooldownSignals map[string]string `json:"cooldown_signals,omitempty"`
// IndependentCooldownSignals persists CooldownSignals for IndependentState.
IndependentCooldownSignals map[string]string `json:"independent_cooldown_signals,omitempty"`
// ForceCooldownUntil persists the exact outer ErrorCodeForceCooldown deadline
// (credQuotaForceUntil for wrapped model records, model/auth forceCooldownUntil otherwise),
// preventing longer ordinary extensions or sibling shadows from inflating it on restore.
ForceCooldownUntil time.Time `json:"force_cooldown_until,omitempty"`
// CredQuotaForceCooldownUntil persists auth-level credential_quota force provenance
// independently from model-less auth ForceCooldownUntil when both coexist on an auth.
CredQuotaForceCooldownUntil time.Time `json:"cred_quota_force_cooldown_until,omitempty"`
// IndependentForceCooldownUntil persists the exact ErrorCodeForceCooldown deadline
// for IndependentState beneath a credential_quota wrap.
IndependentForceCooldownUntil time.Time `json:"independent_force_cooldown_until,omitempty"`
// ForceCooldownEvaluated marks records produced by provenance-aware versions so
// a zero ForceCooldownUntil means "explicitly ordinary" rather than legacy unknown.
ForceCooldownEvaluated bool `json:"force_cooldown_evaluated,omitempty"`
// CredentialRetryAfter persists a non-429 credential-wide retry deadline so
// restart recovery blocks all models even when ModelStates also exist.
CredentialRetryAfter time.Time `json:"credential_retry_after,omitempty"`
}
CooldownStateRecord is a persisted runtime cooldown snapshot for one auth/model pair.
type CooldownStateStore ¶
type CooldownStateStore interface {
Load(context.Context) ([]CooldownStateRecord, error)
Save(context.Context, []CooldownStateRecord) error
}
CooldownStateStore persists runtime cooldown state independently from auth tokens.
type CooldownStateStoreProvider ¶
type CooldownStateStoreProvider interface {
CooldownStateStore() CooldownStateStore
}
CooldownStateStoreProvider exposes a backend-specific cooldown state store.
type CooldownView ¶
type CooldownView struct {
Scope string `json:"scope"`
ModelKey string `json:"model_key,omitempty"`
Reason string `json:"reason"`
RetryAt time.Time `json:"retry_at"`
RemainingSeconds int64 `json:"remaining_seconds"`
BackoffLevel *int `json:"backoff_level,omitempty"`
HTTPStatus int `json:"http_status,omitempty"`
}
CooldownView describes an unexpired local retry restriction, not overall credential availability. It contains no credential metadata or raw errors.
func CooldownSnapshotForAuth ¶
func CooldownSnapshotForAuth(auth *Auth, now time.Time) []CooldownView
CooldownSnapshotForAuth projects a detached auth snapshot without mutating it. It reports timers even when another restriction (such as disablement or an expired token) also prevents execution. An empty result does not imply that the credential is usable. Callers must handle unavailable/remote state separately.
type Error ¶
type Error struct {
// Code is a short machine readable identifier.
Code string `json:"code,omitempty"`
// Message is a human readable description of the failure.
Message string `json:"message"`
// Retryable indicates whether a retry might fix the issue automatically.
Retryable bool `json:"retryable"`
// HTTPStatus optionally records an HTTP-like status code for the error.
HTTPStatus int `json:"http_status,omitempty"`
// Metadata carries optional provider-specific detail extracted from the
// upstream failure (for example an Antigravity TOS appeal URL) so the
// conductor can persist it on the credential record for operator tooling.
Metadata map[string]string `json:"metadata,omitempty"`
}
Error describes an authentication related failure in a provider agnostic format.
func NewRequestScopedError ¶
NewRequestScopedError creates an Error explicitly flagged as request-scoped so that credential cooldown is skipped.
func ResultErrorFromError ¶ added in v8.0.70
ResultErrorFromError classifies an execution or transport error into an auth.Error while preserving lifecycle and transient transport classifications so MarkResult does not cool credentials on client cancellations or network drops.
func (*Error) Clone ¶ added in v8.0.70
Clone returns an independent copy of the error, deep-copying the Metadata map so snapshots cannot share mutable state with the original.
func (*Error) ErrorCode ¶ added in v8.0.57
ErrorCode returns the machine-readable error code embedded in the Error.
func (*Error) IsRequestScoped ¶
IsRequestScoped reports whether the failure is tied to the current request rather than the selected credential.
func (*Error) MarkRequestScoped ¶
MarkRequestScoped marks the error as request-scoped in place and returns it.
func (*Error) StatusCode ¶
StatusCode implements optional status accessor for manager decision making.
type ExecutionSessionCloser ¶
type ExecutionSessionCloser interface {
CloseExecutionSession(sessionID string)
}
ExecutionSessionCloser allows executors to release per-session runtime resources.
type ExecutionSessionSharer ¶ added in v8.0.26
type ExecutionSessionSharer interface {
}
ExecutionSessionSharer reports whether a replaced executor shares its execution session store with the replacement executor so active sessions stay open.
type FileCooldownStateStore ¶
type FileCooldownStateStore struct {
// contains filtered or unexported fields
}
FileCooldownStateStore stores cooldown state as one .cds file per auth.
func NewFileCooldownStateStore ¶
func NewFileCooldownStateStore(dir string) *FileCooldownStateStore
NewFileCooldownStateStore creates a file-backed cooldown state store rooted at dir.
func NewFileCooldownStateStoreWithAuthDir ¶
func NewFileCooldownStateStoreWithAuthDir(dir, authDir string) *FileCooldownStateStore
NewFileCooldownStateStoreWithAuthDir creates a store and derives per-auth .cds paths from auth files relative to authDir when possible.
func (*FileCooldownStateStore) Load ¶
func (s *FileCooldownStateStore) Load(ctx context.Context) ([]CooldownStateRecord, error)
Load reads all cooldown state files. A missing directory is treated as empty state.
func (*FileCooldownStateStore) Save ¶
func (s *FileCooldownStateStore) Save(ctx context.Context, records []CooldownStateRecord) error
Save atomically writes one cooldown state file per auth and removes stale files.
type FillFirstSelector ¶
type FillFirstSelector struct{}
FillFirstSelector selects the first available credential (deterministic ordering). This "burns" one account before moving to the next, which can help stagger rolling-window subscription caps (e.g. chat message limits).
type ForceRefreshResult ¶
type ForceRefreshResult struct {
ID string `json:"id"`
Success bool `json:"success"`
Error string `json:"error,omitempty"`
}
ForceRefreshResult records the outcome of a forced refresh for one credential.
type HomeConcurrencyBusyError ¶
type HomeConcurrencyBusyError struct {
// contains filtered or unexported fields
}
HomeConcurrencyBusyError is a trusted, Home-originated concurrency admission failure.
func (*HomeConcurrencyBusyError) Error ¶
func (e *HomeConcurrencyBusyError) Error() string
func (*HomeConcurrencyBusyError) RetryAfter ¶
func (e *HomeConcurrencyBusyError) RetryAfter() *time.Duration
func (*HomeConcurrencyBusyError) SafeResponseHeaders ¶
func (e *HomeConcurrencyBusyError) SafeResponseHeaders() http.Header
func (*HomeConcurrencyBusyError) StatusCode ¶
func (e *HomeConcurrencyBusyError) StatusCode() int
func (*HomeConcurrencyBusyError) Unwrap ¶
func (e *HomeConcurrencyBusyError) Unwrap() error
Unwrap preserves the Home error's code, retryability, and status for errors.As callers.
type HomeDispatchBundle ¶
type HomeDispatchBundle struct {
// contains filtered or unexported fields
}
HomeDispatchBundle is the immutable client and registry pair for one Home lifetime.
type HomeDispatchSelection ¶
type HomeDispatchSelection struct {
Auth *Auth
Executor ProviderExecutor
Provider string
CanonicalSessionID string
ParentSessionID string
// contains filtered or unexported fields
}
HomeDispatchSelection keeps a Home execution scope separate from its auth.
func (*HomeDispatchSelection) Active ¶
func (s *HomeDispatchSelection) Active() bool
Active reports whether the selection has not ended.
func (*HomeDispatchSelection) AttemptContext ¶
func (s *HomeDispatchSelection) AttemptContext(ctx context.Context) (context.Context, func(), error)
AttemptContext creates a selection-owned context and returns its release function.
func (*HomeDispatchSelection) Bind ¶
func (s *HomeDispatchSelection) Bind(closeFn func() error) error
Bind adds a resource to be closed when this selection ends or drains.
func (*HomeDispatchSelection) CloneAuth ¶
func (s *HomeDispatchSelection) CloneAuth() *Auth
CloneAuth returns a standalone auth copy without the selection handle.
func (*HomeDispatchSelection) CloneAuthForRoute ¶
func (s *HomeDispatchSelection) CloneAuthForRoute(routeModel string) *Auth
CloneAuthForRoute returns an auth copy adapted for a retained canonical route.
func (*HomeDispatchSelection) End ¶
func (s *HomeDispatchSelection) End(reason string)
End closes all bound resources and releases the Home execution scope once.
func (*HomeDispatchSelection) EndWebsocketTurn ¶ added in v8.0.45
func (s *HomeDispatchSelection) EndWebsocketTurn(ctx context.Context, reason string)
EndWebsocketTurn releases a selection whose websocket was lost while the attempt of ctx still has to deliver the turn error: that attempt is not cancelled. Its own release (or the request context) ends it.
func (*HomeDispatchSelection) EndWithRelease ¶
func (s *HomeDispatchSelection) EndWithRelease(reason string) *executionregistry.ReleaseTicket
EndWithRelease closes all bound resources and returns the Home release ticket.
func (*HomeDispatchSelection) ReplaceAuth ¶
func (s *HomeDispatchSelection) ReplaceAuth(auth *Auth)
ReplaceAuth updates the selection after Home returns refreshed credentials.
func (*HomeDispatchSelection) Retain ¶
func (s *HomeDispatchSelection) Retain()
Retain transfers selection ownership from a request to an execution session.
func (*HomeDispatchSelection) Retained ¶
func (s *HomeDispatchSelection) Retained() bool
Retained reports whether an executor transferred this selection to a session.
type HomeInFlightPublisherConfig ¶
type HomeInFlightPublisherConfig struct {
SnapshotInterval time.Duration
MaxPartBytes int
MaxPartCount int
MaxRevisionBytes int
MaxAggregateGroups int
MaxDetails int
MaxStringBytes int
}
HomeInFlightPublisherConfig bounds in-flight observation frames.
func HomeInFlightPublisherConfigFromConfig ¶
func HomeInFlightPublisherConfigFromConfig(cfg internalconfig.CredentialInFlightConfig) (HomeInFlightPublisherConfig, error)
HomeInFlightPublisherConfigFromConfig converts validated runtime config into publisher bounds.
type HomeInFlightTransport ¶
type HomeInFlightTransport interface {
HeartbeatOK() bool
LPushInFlightSnapshot(context.Context, []byte) error
}
HomeInFlightTransport publishes in-flight observation frames for one Home lifetime.
type Hook ¶
type Hook interface {
// OnAuthRegistered fires when a new auth is registered.
OnAuthRegistered(ctx context.Context, auth *Auth)
// OnAuthUpdated fires when an existing auth changes state.
OnAuthUpdated(ctx context.Context, auth *Auth)
// OnResult fires when execution result is recorded.
OnResult(ctx context.Context, result Result)
}
Hook captures lifecycle callbacks for observing auth changes.
type InFlightSnapshot ¶ added in v8.0.70
type InFlightSnapshot struct {
InFlight int64
OldestStartedAt time.Time
ByProvider map[string]int64
}
InFlightSnapshot is an immutable view of standalone in-flight executions.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager orchestrates auth lifecycle, selection, execution, and persistence.
func NewManager ¶
NewManager constructs a manager with optional custom selector and hook.
func (*Manager) ApplyConfigWithCooldownStateStore ¶
func (m *Manager) ApplyConfigWithCooldownStateStore(ctx context.Context, cfg *internalconfig.Config, store CooldownStateStore) bool
ApplyConfigWithCooldownStateStore serializes a config update with its cooldown store transition. It persists the resulting state to the captured old store before exposing the resolved replacement store.
func (*Manager) ApplyHomeInFlightPublisherConfig ¶
func (m *Manager) ApplyHomeInFlightPublisherConfig(cfg HomeInFlightPublisherConfig)
ApplyHomeInFlightPublisherConfig stores an immutable validated publisher config snapshot.
func (*Manager) ApplyRequestScopedErrorResult ¶ added in v8.0.70
func (m *Manager) ApplyRequestScopedErrorResult(ctx context.Context, auth *Auth, err error, result *Result) (string, bool)
ApplyRequestScopedErrorResult evaluates request-scoped error rules for auth and applies any matched action code onto result before MarkResult.
func (*Manager) AvailableProviders ¶
AvailableProviders returns the set of provider keys that currently have at least one registered auth record that is not disabled. It is a best-effort snapshot for routing decisions and does not account for per-model cooldowns or transient runtime availability. Disabled auths (Disabled flag or StatusDisabled) are excluded so routing does not target providers that auth selection would refuse to use, which would otherwise cause execution failures instead of falling back to lower-priority routers.
func (*Manager) BindCodexSIWC ¶ added in v8.0.35
func (m *Manager) BindCodexSIWC(ctx context.Context, id string, expectedEpoch uint64, expectedAccount string, tokenData *codex.CodexSIWCTokenData) (*Auth, error)
BindCodexSIWC explicitly replaces the SIWC partition of an existing file-backed Codex registration. Unlike ordinary persistence, a failed write never publishes credentials. expectedEpoch and expectedAccount must match the registration captured before OAuth.
func (*Manager) ClearHomeDispatchBundle ¶
func (m *Manager) ClearHomeDispatchBundle(bundle *HomeDispatchBundle) bool
ClearHomeDispatchBundle removes bundle only when it still belongs to the active lifetime.
func (*Manager) ClearHomeExecutionRegistry ¶
func (m *Manager) ClearHomeExecutionRegistry(registry *executionregistry.Registry) bool
ClearHomeExecutionRegistry removes a matching legacy registry bundle.
func (*Manager) CloseExecutionSession ¶
CloseExecutionSession asks all registered executors to release the supplied execution session.
func (*Manager) Execute ¶
func (m *Manager) Execute(ctx context.Context, providers []string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error)
func (*Manager) ExecuteCount ¶
func (m *Manager) ExecuteCount(ctx context.Context, providers []string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error)
It supports multiple providers for the same model and round-robins the starting provider per model.
func (*Manager) ExecuteStream ¶
func (m *Manager) ExecuteStream(ctx context.Context, providers []string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (result *cliproxyexecutor.StreamResult, err error)
ExecuteStream performs a streaming execution using the configured selector and executor. It supports multiple providers for the same model and round-robins the starting provider per model.
func (*Manager) Executor ¶
func (m *Manager) Executor(provider string) (ProviderExecutor, bool)
Executor returns the registered provider executor for a provider key.
func (*Manager) ForceRefreshAll ¶
func (m *Manager) ForceRefreshAll(ctx context.Context) []ForceRefreshResult
ForceRefreshAll triggers an immediate refresh for all credentials that have refresh tokens or custom refresh evaluators.
func (*Manager) ForceRefreshAuth ¶
ForceRefreshAuth triggers an immediate synchronous refresh for the credential.
func (*Manager) GetExecutionSessionAuthByID ¶
GetExecutionSessionAuthByID retrieves a Home runtime auth scoped to an execution session.
func (*Manager) HasAlternativeTargetForModel ¶ added in v8.0.56
func (m *Manager) HasAlternativeTargetForModel(ctx context.Context, providers []string, model string, opts cliproxyexecutor.Options, excludedAuthID string) bool
HasAlternativeTargetForModel reports whether at least one eligible credential other than excludedAuthID can serve model across providers.
func (*Manager) HasProviderAuth ¶
HasProviderAuth reports whether at least one non-disabled auth record is registered for the provider. Disabled auths (Disabled flag or StatusDisabled) are excluded to match the behavior of auth selection, which refuses to pick disabled credentials.
func (*Manager) HomeDispatchBundle ¶
func (m *Manager) HomeDispatchBundle() *HomeDispatchBundle
HomeDispatchBundle returns the active Home lifetime bundle.
func (*Manager) HomeEnabled ¶
HomeEnabled reports whether the home control plane integration is enabled in the runtime config.
func (*Manager) HomeExecutionRegistry ¶
func (m *Manager) HomeExecutionRegistry() *executionregistry.Registry
HomeExecutionRegistry returns the registry from the active Home lifetime bundle.
func (*Manager) HomeInFlightPublisherConfig ¶
func (m *Manager) HomeInFlightPublisherConfig() HomeInFlightPublisherConfig
HomeInFlightPublisherConfig returns the current immutable publisher config snapshot.
func (*Manager) HttpRequest ¶
func (m *Manager) HttpRequest(ctx context.Context, auth *Auth, req *http.Request) (*http.Response, error)
HttpRequest injects provider credentials into the supplied HTTP request and executes it.
func (*Manager) InFlightSnapshot ¶ added in v8.0.70
func (m *Manager) InFlightSnapshot() InFlightSnapshot
InFlightSnapshot returns the current standalone in-flight execution counts. It reports an empty snapshot while Home mode is enabled, where the execution registry is the authoritative in-flight source instead.
func (*Manager) InjectCredentials ¶
InjectCredentials delegates per-provider HTTP request preparation when supported. If the registered executor for the auth provider implements RequestPreparer, it will be invoked to modify the request (e.g., add headers).
func (*Manager) LookupSessionAffinity ¶
LookupSessionAffinity observes the current session affinity binding without side effects. It returns (auth, status) where status can be "bound", "unbound", "ambiguous", or "unsupported".
func (*Manager) MarkResult ¶
MarkResult records an execution result and notifies hooks.
func (*Manager) MaxRetryCredentials ¶ added in v8.0.70
MaxRetryCredentials returns the configured per-request credential retry cap (0 means unlimited).
func (*Manager) Modify ¶ added in v8.0.34
func (m *Manager) Modify(ctx context.Context, id string, expectedEpoch uint64, edit func(*Auth) error) (*Auth, bool, error)
Modify loads the latest auth for id while holding the per-auth mutation gate, applies edit to a clone of that auth, and commits the result through the standard persistence and publication path. It returns (nil, false, nil) if the auth is not present when the gate is acquired.
func (*Manager) NewHttpRequest ¶
func (m *Manager) NewHttpRequest(ctx context.Context, auth *Auth, method, targetURL string, body []byte, headers http.Header) (*http.Request, error)
NewHttpRequest constructs a new HTTP request and injects provider credentials into it.
func (*Manager) NextExecutionSeq ¶ added in v8.0.70
nextExecutionSeq stamps a new upstream dispatch with the next monotonic execution sequence. The stamp travels on the execution's Result so that MarkResult can order the execution against cooldowns recorded meanwhile. NextExecutionSeq allocates the next monotonic execution sequence number for ordering concurrent MarkResult updates against newly recorded cooldowns.
func (*Manager) PersistCooldownStates ¶
PersistCooldownStates writes the current cooldown snapshot using ctx.
func (*Manager) PersistMetadataEntry ¶ added in v8.0.24
func (m *Manager) PersistMetadataEntry(ctx context.Context, id string, expectedEpoch uint64, key string, value any, validate func(existing *Auth) bool) (bool, bool)
PersistMetadataEntry updates a single metadata entry on the runtime auth for the given registration epoch and persists it to the backing store without advancing Generation or firing credential-lifecycle hooks. If a foreground credential mutation contends for the same auth while store I/O is in flight, the metadata save is preempted so foreground operations do not stall.
func (*Manager) PluginSchedulerWantsAcrossPriorities ¶
PluginSchedulerWantsAcrossPriorities reports whether the configured plugin scheduler opted into receiving candidates across all priority tiers.
func (*Manager) PrepareHttpRequest ¶
PrepareHttpRequest injects provider credentials into the supplied HTTP request.
func (*Manager) PrepareRequestAuth ¶
func (m *Manager) PrepareRequestAuth(ctx context.Context, preparer RequestAuthPreparer, auth *Auth) (*Auth, error)
PrepareRequestAuth prepares a registered credential using the same serialization and lifecycle checks as normal request execution. Management tools use this path too.
func (*Manager) PublishHomeDispatch ¶
func (m *Manager) PublishHomeDispatch(client homeAuthDispatcher, registry *executionregistry.Registry, generation uint64) *HomeDispatchBundle
PublishHomeDispatch publishes the selectable Home lifetime as one atomic bundle.
func (*Manager) PublishIfRegistrationCurrent ¶ added in v8.0.29
func (m *Manager) PublishIfRegistrationCurrent(id string, registrationEpoch uint64, prefix, provider string, disabled bool, authKind string, attributes map[string]string, publish func() bool) bool
PublishIfRegistrationCurrent serializes the final model-registration publication against identity mutations for this auth, then calls publish only if the manager still holds auth with the same model-registration inputs. It does not persist or clone auth state. publish must be fast and must not re-enter the manager.
func (*Manager) ReconcileRegistryModelStates ¶
ReconcileRegistryModelStates aligns per-model runtime state with the current registry snapshot for one auth.
Active cooldown and quota states for supported models (including models reachable via alias routes) are preserved, while stale/expired errors on supported models are reset. ModelStates for models that are no longer reachable either directly or via alias routes are pruned entirely so renamed/removed models cannot keep auth-level status stale.
func (*Manager) RefreshAPIKeyModelAlias ¶
func (m *Manager) RefreshAPIKeyModelAlias()
RefreshAPIKeyModelAlias rebuilds the API-key model alias table from the current runtime config.
func (*Manager) RefreshAfterUnauthorized ¶ added in v8.0.70
func (m *Manager) RefreshAfterUnauthorized(ctx context.Context, auth *Auth, execErr error, alreadyTried bool, clientHeaders ...http.Header) (*Auth, bool)
RefreshAfterUnauthorized refreshes a local credential once after an upstream 401 using the same rejection-marking and single-refresh rules as request execution.
func (*Manager) RefreshHomeSelectionAfterUnauthorized ¶
func (m *Manager) RefreshHomeSelectionAfterUnauthorized(ctx context.Context, selection *HomeDispatchSelection, failedAuth *Auth) (*Auth, bool, error)
RefreshHomeSelectionAfterUnauthorized only reuses a newer snapshot already installed by Home. It never refreshes or mutates Home-owned credentials.
func (*Manager) RefreshSchedulerAll ¶
func (m *Manager) RefreshSchedulerAll()
RefreshSchedulerAll rebuilds scheduler entries for every known auth.
func (*Manager) RefreshSchedulerEntry ¶
RefreshSchedulerEntry re-upserts a single auth into the scheduler so that its supportedModelSet is rebuilt from the current global model registry state. This must be called after models have been registered for a newly added auth, because the initial scheduler.upsertAuth during Register/Update runs before registerModelsForAuth and therefore snapshots an empty model set.
func (*Manager) RegisterExecutor ¶
func (m *Manager) RegisterExecutor(executor ProviderExecutor)
RegisterExecutor registers a provider executor with the manager.
func (*Manager) Remove ¶
Remove deletes an auth from runtime state without persisting. Disk and token-store deletion must be handled by the caller.
func (*Manager) RemoveIf ¶ added in v8.0.49
RemoveIf deletes an auth from runtime state while holding the per-auth mutation gate when predicate is nil or returns true for the current auth.
func (*Manager) ReportHomeUnauthorized ¶
func (m *Manager) ReportHomeUnauthorized(ctx context.Context, auth *Auth, provider, model string, upstreamBody ...[]byte)
ReportHomeUnauthorized publishes a result-only zero-token usage record for an upstream 401 attempt that did not pass through an executor UsageReporter.
func (*Manager) ResetQuota ¶
ResetQuota clears quota/cooldown state for an auth and resumes registry routing.
func (*Manager) ResolveExecutionModel ¶
ResolveExecutionModel returns the credential-aware upstream model used by normal execution. It strips auth prefixes, applies configured aliases, and prefers Home-dispatched upstream models when present.
func (*Manager) RestoreCooldownStates ¶
RestoreCooldownStates restores unexpired persisted cooldown records into registered auths.
func (*Manager) ResultPolicy ¶
func (m *Manager) ResultPolicy() ResultPolicy
ResultPolicy returns the current execution result policy, or nil if none is configured.
func (*Manager) SelectAuth ¶
func (m *Manager) SelectAuth(ctx context.Context, provider, model string, opts cliproxyexecutor.Options) (*Auth, error)
SelectAuth selects one credential through the configured scheduling strategy. It does not execute or alter the selected credential's result state.
func (*Manager) SelectAuthByKind ¶
func (m *Manager) SelectAuthByKind(ctx context.Context, provider, model, requiredKind string, opts cliproxyexecutor.Options) (*Auth, error)
SelectAuthByKind selects one credential of the required kind through the configured scheduling strategy. Credentials of other kinds are skipped.
func (*Manager) SelectAuthExcluding ¶ added in v8.0.70
func (m *Manager) SelectAuthExcluding(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, tried map[string]struct{}) (*Auth, error)
SelectAuthExcluding selects one credential through the configured scheduling strategy while excluding any credential IDs present in tried.
func (*Manager) SelectAuthWithCredentialPolicy ¶
func (m *Manager) SelectAuthWithCredentialPolicy(ctx context.Context, provider, model, policy string, opts cliproxyexecutor.Options) (*Auth, error)
SelectAuthWithCredentialPolicy selects one local credential allowed by a fixed policy.
func (*Manager) SelectHomeAuthByKind ¶
func (m *Manager) SelectHomeAuthByKind(ctx context.Context, provider string, model string, requiredKind string, opts cliproxyexecutor.Options) (*HomeDispatchSelection, error)
SelectHomeAuthByKind selects a Home dispatch while retaining its execution scope.
func (*Manager) SelectHomeAuthWithCredentialPolicy ¶
func (m *Manager) SelectHomeAuthWithCredentialPolicy(ctx context.Context, provider, model, policy string, opts cliproxyexecutor.Options) (*HomeDispatchSelection, error)
SelectHomeAuthWithCredentialPolicy selects a policy-constrained Home dispatch while retaining its execution scope.
func (*Manager) SetConfig ¶
func (m *Manager) SetConfig(cfg *internalconfig.Config)
SetConfig updates the runtime config snapshot used by request-time helpers. Callers should provide the latest config on reload so per-credential alias mapping stays in sync.
func (*Manager) SetConfigSnapshot ¶
func (m *Manager) SetConfigSnapshot(cfg *internalconfig.Config) bool
SetConfigSnapshot updates only in-memory configuration state. It reports whether a caller must persist cleared cooldown state after its commit critical section.
func (*Manager) SetCooldownStateStore ¶
func (m *Manager) SetCooldownStateStore(store CooldownStateStore)
SetCooldownStateStore swaps the independent runtime cooldown state store.
func (*Manager) SetHomeExecutionRegistry ¶
func (m *Manager) SetHomeExecutionRegistry(registry *executionregistry.Registry)
SetHomeExecutionRegistry preserves the legacy registry API for callers that also install the current dispatcher.
func (*Manager) SetOAuthModelAlias ¶
func (m *Manager) SetOAuthModelAlias(aliases map[string][]internalconfig.OAuthModelAlias)
SetOAuthModelAlias updates the OAuth model name alias table used during execution. The alias is applied per-auth channel to resolve the upstream model name while keeping the client-visible model name unchanged for translation/response formatting.
func (*Manager) SetPluginScheduler ¶
func (m *Manager) SetPluginScheduler(scheduler PluginScheduler)
func (*Manager) SetResultPolicy ¶
func (m *Manager) SetResultPolicy(policy ResultPolicy)
SetResultPolicy sets an execution result policy invoked before in-memory quota mutations and persistence.
func (*Manager) SetRetryConfig ¶
func (m *Manager) SetRetryConfig(retry int, maxRetryInterval time.Duration, maxRetryCredentials int)
SetRetryConfig updates additional credential retry rounds, the per-round credential limit, and the cooldown wait interval.
func (*Manager) SetRoundTripperProvider ¶
func (m *Manager) SetRoundTripperProvider(p RoundTripperProvider)
SetRoundTripperProvider register a provider that returns a per-auth RoundTripper.
func (*Manager) SetSelector ¶
func (*Manager) StartAutoRefresh ¶
StartAutoRefresh launches a background loop that evaluates auth freshness every few seconds and triggers refresh operations when required. Only one loop is kept alive; starting a new one cancels the previous run.
func (*Manager) StartHomeInFlightPublisher ¶
func (m *Manager) StartHomeInFlightPublisher(ctx context.Context, transport HomeInFlightTransport, registry *executionregistry.Registry)
StartHomeInFlightPublisher publishes periodic snapshots for the supplied lifetime registry.
func (*Manager) StopAutoRefresh ¶
func (m *Manager) StopAutoRefresh()
StopAutoRefresh cancels the background refresh loop, if running. It also stops the selector if it implements StoppableSelector.
func (*Manager) SupportsApplyPatchForProviders ¶ added in v8.0.9
SupportsApplyPatchForProviders requires support from every routing candidate.
func (*Manager) SupportsNativeToolSearchForModel ¶ added in v8.0.24
SupportsNativeToolSearchForModel requires native tool search support from every enabled credential that serves the public model. A prefixed ID that no credential registers exactly falls back to its unprefixed form. A model with no serving credential is not supported.
func (*Manager) SwapCooldownStateStore ¶
func (m *Manager) SwapCooldownStateStore(ctx context.Context, store CooldownStateStore, persistOld bool) bool
SwapCooldownStateStore persists cleared state to the old store before replacing it. Persistence is deliberately performed without holding the manager lock.
func (*Manager) UnregisterExecutor ¶
UnregisterExecutor removes the executor associated with the provider key.
func (*Manager) UpdateIfRegistrationCurrent ¶ added in v8.0.29
func (m *Manager) UpdateIfRegistrationCurrent(ctx context.Context, base *Auth, updated *Auth) (*Auth, bool, error)
UpdateIfRegistrationCurrent applies a plugin-returned auth update only while the manager still holds the exact registration inputs the plugin computation started from. It prevents an old plugin result from adopting a removed or re-registered identity merely because its zero registration epoch would otherwise inherit the current epoch during Update.
func (*Manager) UpdatePreparedAuth ¶
UpdatePreparedAuth atomically merges request preparation results into the latest runtime auth under the manager lock, preserving concurrent modifications without modifying refresh lifecycle fields.
func (*Manager) UpdateRefreshedAuth ¶
UpdateRefreshedAuth atomically merges refresh results into the latest runtime auth under the manager lock, preserving concurrent modifications (proxy_url, notes, weights, etc.).
func (*Manager) VerifyInference ¶ added in v8.0.48
VerifyInference performs an operator-triggered, account-pinned inference verification using an isolated session and minimal non-user prompt/token budget. It never falls back to another credential and requires a completed response before marking InferenceVerified.
func (*Manager) WatchAuthChanges ¶ added in v8.0.14
WatchAuthChanges observes structural changes to one runtime credential, including token preparation/refresh, replacement, removal and store reload. Notifications are coalesced: consumers must inspect the latest manager state. The caller must unsubscribe when its work ends. Request result accounting does not notify watchers, so ordinary Generation increments do not invalidate work.
type ModelState ¶
type ModelState struct {
// Status reflects the lifecycle status for this model.
Status Status `json:"status"`
// StatusMessage provides an optional short description of the status.
StatusMessage string `json:"status_message,omitempty"`
Unavailable bool `json:"unavailable"`
// NextRetryAfter defines the per-model retry time.
NextRetryAfter time.Time `json:"next_retry_after"`
// LastError records the latest error observed for this model.
LastError *Error `json:"last_error,omitempty"`
// Quota retains quota information if this model hit rate limits.
Quota QuotaState `json:"quota"`
// UpdatedAt tracks the last update timestamp for this model state.
UpdatedAt time.Time `json:"updated_at"`
// contains filtered or unexported fields
}
ModelState captures the execution state for a specific model under an auth entry.
func (*ModelState) Clone ¶
func (m *ModelState) Clone() *ModelState
Clone duplicates a model state including nested error details.
type NativeToolSearchSupport ¶ added in v8.0.24
type NativeToolSearchSupport interface {
SupportsNativeToolSearch(auth *Auth, upstreamModel string) bool
}
NativeToolSearchSupport optionally reports whether an executor can send Codex tool_search to a credential as Anthropic native tool search. It does not change ProviderExecutor or the plugin ABI.
type NoopHook ¶
type NoopHook struct{}
NoopHook provides optional hook defaults.
func (NoopHook) OnAuthRegistered ¶
OnAuthRegistered implements Hook.
func (NoopHook) OnAuthUpdated ¶
OnAuthUpdated implements Hook.
type OAuthModelAliasResult ¶
type OAuthModelAliasResult struct {
UpstreamModel string // resolved upstream model name (empty if no mapping found)
ForceMapping bool // whether to rewrite model name in responses
OriginalAlias string // client-visible model for response rewrite; only applied when ForceMapping is true (see rewriteForceMappedResponse / wrapStreamResult)
}
OAuthModelAliasResult contains the resolved upstream model and mapping metadata.
type PluginScheduler ¶
type PluginScheduler interface {
PickAuth(context.Context, pluginapi.SchedulerPickRequest) (pluginapi.SchedulerPickResponse, bool, error)
}
type PluginSchedulerAcrossPriorities ¶
type PluginSchedulerAcrossPriorities interface {
SchedulerWantsAcrossPriorities() bool
}
PluginSchedulerAcrossPriorities is an optional interface implemented by schedulers that opt into receiving candidates across all priority tiers.
type PostAuthHook ¶
PostAuthHook defines a function that is called after an Auth record is created but before it is persisted to storage. This allows for modification of the Auth record (e.g., injecting metadata) based on external context.
type ProviderExecutor ¶
type ProviderExecutor interface {
// Identifier returns the provider key handled by this executor.
Identifier() string
// Execute handles non-streaming execution and returns the provider response payload.
Execute(ctx context.Context, auth *Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error)
// ExecuteStream handles streaming execution and returns a StreamResult containing
// upstream headers and a channel of provider chunks.
ExecuteStream(ctx context.Context, auth *Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (*cliproxyexecutor.StreamResult, error)
// Refresh attempts to refresh provider credentials and returns the updated auth state.
Refresh(ctx context.Context, auth *Auth) (*Auth, error)
// CountTokens returns the token count for the given request.
CountTokens(ctx context.Context, auth *Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error)
// HttpRequest injects provider credentials into the supplied HTTP request and executes it.
// Callers must close the response body when non-nil.
HttpRequest(ctx context.Context, auth *Auth, req *http.Request) (*http.Response, error)
}
ProviderExecutor defines the contract required by Manager to execute provider calls.
type ProxyConnectionPoolOverride ¶ added in v8.0.50
type ProxyConnectionPoolOverride struct {
Enabled *bool `json:"enabled,omitempty"`
IdleConnTimeout string `json:"idle-conn-timeout,omitempty"`
MaxIdleConnsPerHost *int `json:"max-idle-conns-per-host,omitempty"`
}
ProxyConnectionPoolOverride holds the per-api-key connection-pool settings. Omitted fields fall back to the pool defaults (300s idle, 2 idle per host).
func (*ProxyConnectionPoolOverride) Clone ¶ added in v8.0.50
func (o *ProxyConnectionPoolOverride) Clone() *ProxyConnectionPoolOverride
type QuotaState ¶
type QuotaState struct {
// Exceeded indicates the credential recently hit a quota error.
Exceeded bool `json:"exceeded"`
// Reason provides an optional provider specific human readable description.
Reason string `json:"reason,omitempty"`
// NextRecoverAt is when the credential may become available again.
NextRecoverAt time.Time `json:"next_recover_at"`
// BackoffLevel stores the progressive cooldown exponent used for rate limits.
BackoffLevel int `json:"backoff_level,omitempty"`
// ObservedAt is the time the current Signals snapshot was observed.
ObservedAt time.Time `json:"observed_at,omitempty"`
// Signals stores bounded, provider-specific quota watermark values observed
// from upstream response headers or websocket quota events. It is a snapshot
// of one upstream response, not an accumulation across responses, so an
// expired watermark cannot linger after the response that produced it.
// Cooldown transitions must use applyCooldownFields so they cannot replace
// this snapshot.
Signals map[string]string `json:"signals,omitempty"`
// contains filtered or unexported fields
}
QuotaState contains limiter tracking data for a credential.
func (*QuotaState) ClearObservationSignals ¶
func (q *QuotaState) ClearObservationSignals() bool
ClearObservationSignals removes only passive observation data. It leaves cooldown and scheduler state untouched.
func (QuotaState) Clone ¶
func (q QuotaState) Clone() QuotaState
Clone returns an independent copy of the quota state.
func (*QuotaState) ObserveResponseHeadersForProvider ¶
func (q *QuotaState) ObserveResponseHeadersForProvider(provider string, headers http.Header, observedAt time.Time) bool
ObserveResponseHeadersForProvider replaces the passive quota snapshot with the signals carried by the current upstream response.
The snapshot is replaced rather than merged: a watermark such as Retry-After or a "limit reached" flag only appears on the response that produced it, so accumulating signals across responses would leave an expired value visible indefinitely. Responses that carry no quota signal at all (transport failures, 5xx, unrelated endpoints) leave the previous snapshot untouched.
This function only ever touches ObservedAt and Signals. Cooldown and scheduling fields are never read or written here.
type RecentRequestBucket ¶
type RefreshEvaluator ¶
RefreshEvaluator allows runtime state to override refresh decisions.
type RequestAuthPreparer ¶
type RequestAuthPreparer interface {
ShouldPrepareRequestAuth(auth *Auth) bool
PrepareRequestAuth(ctx context.Context, auth *Auth) (*Auth, error)
}
RequestAuthPreparer lets an executor update missing auth metadata immediately before a request. Manager serializes and persists returned updates.
type RequestInfo ¶
RequestInfo holds information extracted from the HTTP request. It is injected into the context passed to PostAuthHook.
func GetRequestInfo ¶
func GetRequestInfo(ctx context.Context) *RequestInfo
GetRequestInfo retrieves the RequestInfo from the context, if present.
type RequestPreparer ¶
RequestPreparer is an optional interface that provider executors can implement to mutate outbound HTTP requests with provider credentials.
type Result ¶
type Result struct {
// AuthID references the auth that produced this result.
AuthID string
// Provider is copied for convenience when emitting hooks.
Provider string
// Model is the upstream model identifier used for the request.
Model string
// RouteModel is the requested logical route model before alias resolution.
RouteModel string
// Success marks whether the execution succeeded.
Success bool
// CompletedResponse reports that the upstream execution produced a completed
// generation response (as opposed to an incomplete stream or non-generation call).
CompletedResponse bool
// RetryAfter carries a provider supplied retry hint (e.g. 429 retryDelay).
RetryAfter *time.Duration
// CredentialScope indicates that the failure affects the whole credential across models (e.g. Anthropic 5h/7d unified limits).
CredentialScope bool
// Error describes the failure when Success is false.
Error *Error
// Options carries execution request options (headers, metadata, etc.) for result tracking.
Options cliproxyexecutor.Options
// SkipQuotaObservation reports that this result must not replace the last
// observed watermark. Count-tokens requests reuse the credential but are not
// generation traffic; their response headers are not a generation snapshot.
SkipQuotaObservation bool
// AccessToken captures the active access token under which the request was executed.
AccessToken string
// RefreshToken captures the refresh credential associated with the request,
// used to distinguish a same-account OAuth token rotation from a genuine
// credential replacement when evaluating result staleness.
RefreshToken string
// CredentialVersion captures the credential version under which the request was executed.
CredentialVersion uint64
// RegistrationEpoch captures the registration epoch under which the request was executed.
RegistrationEpoch uint64
// ExecutionSeq is the manager-local monotonic sequence assigned when the
// execution was dispatched upstream. It orders in-flight executions so a
// success dispatched before a cooldown was recorded cannot clear that
// cooldown. Zero means unknown (direct MarkResult callers) and is exempt
// from the ordering guard.
ExecutionSeq uint64
}
Result captures execution outcome used to adjust auth state.
type ResultPolicy ¶
ResultPolicy allows inspecting and mutating an execution result before in-memory quota mutations, cooldown persistence, and scheduler/registry publishing. Implementations of ResultPolicy must be safe for concurrent use by multiple goroutines.
type ResultPolicyFunc ¶
ResultPolicyFunc enables using a plain function as a ResultPolicy.
func (ResultPolicyFunc) ApplyResultPolicy ¶
func (f ResultPolicyFunc) ApplyResultPolicy(ctx context.Context, result Result) Result
ApplyResultPolicy calls f(ctx, result).
type RoundRobinSelector ¶
type RoundRobinSelector struct {
// contains filtered or unexported fields
}
RoundRobinSelector provides a simple provider scoped round-robin selection strategy.
Rotation continues from the identity of the previous pick rather than from a numeric index. Candidate slices shrink whenever a retry excludes already tried credentials or a credential enters cooldown, and indexing a monotonic counter into a shrinking slice silently re-seats the rotation, which starves some credentials and hammers others.
type RoundTripperProvider ¶
type RoundTripperProvider interface {
RoundTripperFor(auth *Auth) http.RoundTripper
}
RoundTripperProvider defines a minimal provider of per-auth HTTP transports.
type SIWCStatus ¶ added in v8.0.37
type SIWCStatus string
SIWCStatus represents the read-only validity state of a Codex SIWC credential.
const ( SIWCStatusOff SIWCStatus = "off" SIWCStatusValid SIWCStatus = "valid" SIWCStatusInvalid SIWCStatus = "invalid" )
type Selector ¶
type Selector interface {
Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, auths []*Auth) (*Auth, error)
}
Selector chooses an auth candidate for execution.
type SessionAffinityConfig ¶
type SessionAffinityConfig struct {
Fallback Selector
TTL time.Duration
SubagentAffinity *bool
RebindOn string
}
SessionAffinityConfig configures the session affinity selector.
type SessionAffinitySelector ¶
type SessionAffinitySelector struct {
// contains filtered or unexported fields
}
SessionAffinitySelector wraps another selector with session-sticky behavior. It extracts session ID from multiple sources and maintains session-to-auth mappings with automatic failover when the bound auth becomes unavailable.
func NewSessionAffinitySelector ¶
func NewSessionAffinitySelector(fallback Selector) *SessionAffinitySelector
NewSessionAffinitySelector creates a new session-aware selector.
func NewSessionAffinitySelectorWithConfig ¶
func NewSessionAffinitySelectorWithConfig(cfg SessionAffinityConfig) *SessionAffinitySelector
NewSessionAffinitySelectorWithConfig creates a selector with custom configuration.
func (*SessionAffinitySelector) ForgetAuth ¶ added in v8.0.67
func (s *SessionAffinitySelector) ForgetAuth(authID string)
ForgetAuth forwards permanent credential removal to the fallback selector so weighted round-robin accounting can prune deregistered credentials without disturbing credits of transiently excluded credentials.
func (*SessionAffinitySelector) ForgetAuthUpTo ¶ added in v8.0.67
func (s *SessionAffinitySelector) ForgetAuthUpTo(authID string, maxEpoch, maxGen uint64)
ForgetAuthUpTo forwards epoch-gated permanent credential removal to the fallback selector so delayed removals never evict a newly re-registered credential with the same ID.
func (*SessionAffinitySelector) InvalidateAuth ¶
func (s *SessionAffinitySelector) InvalidateAuth(authID string)
InvalidateAuth removes all session bindings for a specific auth. Called when an auth becomes rate-limited or unavailable.
func (*SessionAffinitySelector) LookupAffinity ¶
func (s *SessionAffinitySelector) LookupAffinity(provider, model, sessionID string, authFilters ...func(authID string) bool) (string, string)
LookupAffinity observes the current session affinity binding without side effects. It never selects a credential, creates a binding, rebinds, or refreshes TTL. Optional authFilters allow callers (such as Manager) to exclude credentials that do not match the requested provider.
func (*SessionAffinitySelector) OnResult ¶
func (s *SessionAffinitySelector) OnResult(res Result)
OnResult handles session affinity binding or release based on execution outcome.
func (*SessionAffinitySelector) Pick ¶
func (s *SessionAffinitySelector) Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, auths []*Auth) (selected *Auth, errPick error)
Pick selects an auth with session affinity when possible. Explicit Claude Code, Codex, OpenCode, pi, and request-body session signals are absolute authority. Requests without those signals use the Merkle LCP matcher before retaining the legacy derived/hash fallback behavior.
An established binding outranks credential priority: a bound credential that is still available is reused even when a higher-priority credential recovers. Credential priority applies to cold bindings, requests without a session, and genuine bound-credential failover, so the fallback selector only ever receives the highest available priority tier.
Note: The cache key includes provider, session ID, and model to handle cases where a session uses multiple models (e.g., gemini-2.5-pro and gemini-3-flash-preview) that may be supported by different auth credentials, and to avoid cross-provider conflicts.
func (*SessionAffinitySelector) Stop ¶
func (s *SessionAffinitySelector) Stop()
Stop releases resources held by the selector.
func (*SessionAffinitySelector) Trees ¶
func (s *SessionAffinitySelector) Trees() *cliproxysession.InMemorySessionTreeStore
Trees returns a backward-compatible in-memory session tree store. Deprecated: Session tree management has moved to Home.
type SessionCache ¶
type SessionCache struct {
// contains filtered or unexported fields
}
SessionCache provides TTL-based session to auth mapping with automatic cleanup.
func NewSessionCache ¶
func NewSessionCache(ttl time.Duration) *SessionCache
NewSessionCache creates a cache with the specified TTL. A background goroutine periodically cleans expired entries.
func NewSessionCacheWithCapacity ¶
func NewSessionCacheWithCapacity(ttl time.Duration, maxEntries int) *SessionCache
NewSessionCacheWithCapacity creates a cache with the specified TTL and max entries limit.
func (*SessionCache) CompareAndDelete ¶
func (c *SessionCache) CompareAndDelete(sessionID, expectedAuthID string) bool
CompareAndDelete removes the session binding only if it is currently bound to expectedAuthID.
func (*SessionCache) Get ¶
func (c *SessionCache) Get(sessionID string) (string, bool)
Get retrieves the auth ID bound to a session, if still valid. Does NOT refresh the TTL on access.
func (*SessionCache) GetAndRefresh ¶
func (c *SessionCache) GetAndRefresh(sessionID string) (string, bool)
GetAndRefresh retrieves the auth ID bound to a session and refreshes the TTL for every identifier known to represent the same logical session.
func (*SessionCache) Invalidate ¶
func (c *SessionCache) Invalidate(sessionID string)
Invalidate removes a specific session binding without allowing another alias in the same group to recreate it on its next refresh.
func (*SessionCache) InvalidateAuth ¶
func (c *SessionCache) InvalidateAuth(authID string)
InvalidateAuth removes all sessions bound to a specific auth ID. Used when an auth becomes unavailable.
func (*SessionCache) Len ¶
func (c *SessionCache) Len() int
Len returns the current count of tracked session aliases.
func (*SessionCache) Set ¶
func (c *SessionCache) Set(sessionID, authID string)
Set binds a session to an auth ID with TTL refresh. Existing aliases for the same logical session remain attached when the binding is refreshed or moved.
func (*SessionCache) SetAliases ¶
func (c *SessionCache) SetAliases(authID string, sessionIDs ...string)
SetAliases binds multiple identifiers for one logical session to an auth ID.
func (*SessionCache) Stop ¶
func (c *SessionCache) Stop()
Stop terminates the background cleanup goroutine.
func (*SessionCache) Touch ¶
func (c *SessionCache) Touch(sessionID, expectedAuthID string) bool
Touch refreshes the expiration for a session binding if it currently matches expectedAuthID.
type Status ¶
type Status string
Status represents the lifecycle state of an Auth entry.
const ( // StatusUnknown means the auth state could not be determined. StatusUnknown Status = "unknown" // StatusActive indicates the auth is valid and ready for execution. StatusActive Status = "active" // StatusPending indicates the auth is waiting for an external action, such as MFA. StatusPending Status = "pending" // StatusRefreshing indicates the auth is undergoing a refresh flow. StatusRefreshing Status = "refreshing" // StatusError indicates the auth is temporarily unavailable due to errors. StatusError Status = "error" // StatusDisabled marks the auth as intentionally disabled. StatusDisabled Status = "disabled" )
type StoppableSelector ¶
type StoppableSelector interface {
Selector
Stop()
}
StoppableSelector is an optional interface for selectors that hold resources. Selectors that implement this interface will have Stop called during shutdown.
type Store ¶
type Store interface {
// List returns all auth records stored in the backend.
List(ctx context.Context) ([]*Auth, error)
// Save persists the provided auth record, replacing any existing one with same ID.
// It may enrich exported fields, but must not change ID, RegistrationEpoch,
// CredentialVersion or Generation. The manager merges these changes even on non-fatal save errors.
// Do not retain auth or mutate shared nested values in place: replace metadata
// values, pointers, Storage and Runtime instead. Auth.Clone shares these objects.
// Save may call manager read APIs, but must not synchronously mutate the
// manager or call Load (the reload barrier remains held until publication).
Save(ctx context.Context, auth *Auth) (string, error)
// Delete removes the auth record identified by id.
Delete(ctx context.Context, id string) error
}
Store abstracts persistence of Auth state across restarts.
type StreamRewriteOptions ¶
type StreamRewriteOptions struct {
RewriteModel string
}
StreamRewriteOptions configures the stream rewriter.
type StreamRewriter ¶
type StreamRewriter struct {
// contains filtered or unexported fields
}
StreamRewriter rewrites model names in streaming SSE responses.
func NewStreamRewriter ¶
func NewStreamRewriter(options StreamRewriteOptions) *StreamRewriter
NewStreamRewriter creates a new stream rewriter.
func (*StreamRewriter) Finish ¶
func (r *StreamRewriter) Finish() []byte
Finish flushes any buffered partial SSE data at the end of a stream.
func (*StreamRewriter) RewriteChunk ¶
func (r *StreamRewriter) RewriteChunk(chunk []byte) []byte
RewriteChunk rewrites model names in a single SSE chunk.
type WeightedRoundRobinSelector ¶
type WeightedRoundRobinSelector struct {
// contains filtered or unexported fields
}
WeightedRoundRobinSelector provides smooth weighted round-robin selection.
func UnwrapWeightedRoundRobinSelector ¶ added in v8.0.67
func UnwrapWeightedRoundRobinSelector(selector Selector) *WeightedRoundRobinSelector
UnwrapWeightedRoundRobinSelector extracts the underlying *WeightedRoundRobinSelector from a bare selector or a SessionAffinitySelector wrapper.
func (*WeightedRoundRobinSelector) ForgetAuth ¶ added in v8.0.67
func (s *WeightedRoundRobinSelector) ForgetAuth(authID string)
ForgetAuth removes permanently deregistered credentials from weighted pool state. Transient exclusions (retry tried sets and cooldowns) must never call ForgetAuth.
func (*WeightedRoundRobinSelector) ForgetAuthUpTo ¶ added in v8.0.67
func (s *WeightedRoundRobinSelector) ForgetAuthUpTo(authID string, maxEpoch, maxGen uint64)
ForgetAuthUpTo removes weighted pool entries for authID whose observed (RegistrationEpoch, Generation) is no newer than (maxEpoch, maxGen), so a delayed removal or disablement cannot evict a newly re-registered or re-enabled credential.
Source Files
¶
- antigravity_credits.go
- api_key_model_capabilities.go
- apply_patch_capability.go
- auth_change_watch.go
- auto_refresh_loop.go
- classification.go
- codex_persist.go
- codex_refresh_selection.go
- codex_siwc_bind.go
- conductor.go
- conductor_claude_thread.go
- conductor_cooldown.go
- conductor_execution.go
- conductor_home.go
- conductor_home_execution.go
- conductor_inflight.go
- conductor_lifecycle.go
- conductor_models.go
- conductor_persistence.go
- conductor_refresh.go
- conductor_request_scoped_errors.go
- conductor_selection.go
- conductor_stream.go
- config_apikey.go
- cooldown_state.go
- cooldown_view.go
- credential_policy.go
- custom_headers.go
- error_events.go
- errors.go
- home_concurrency.go
- home_in_flight_publisher.go
- home_result.go
- home_selection.go
- home_session_alias.go
- metadata_keys.go
- metadata_merge.go
- native_tool_search_capability.go
- oauth_model_alias.go
- persist_policy.go
- priority.go
- quota_signals.go
- response_model_rewriter.go
- scheduler.go
- scheduler_weighted.go
- selector.go
- selector_weighted.go
- session_cache.go
- session_resolver.go
- status.go
- store.go
- token_fingerprint.go
- types.go
- weight.go