Documentation
¶
Index ¶
- Constants
- Variables
- func AccessTokenSHA256(auth *Auth) string
- func ApplyCustomHeadersFromMetadata(auth *Auth)
- func ApplyRefreshPendingState(auth *Auth, now time.Time)
- func ApplyRefreshSuccessState(auth *Auth, now time.Time) []string
- func ApplyUnsupportedRefreshBackoff(auth *Auth, now time.Time)
- func AuthIsNewerThanObserved(auth *Auth, observedAccessTokenSHA256 string) bool
- func CanUseObservedTokenAfterRefreshFailure(auth *Auth, observedAccessTokenSHA256 string, errRefresh error, now time.Time) bool
- func CanonicalModelID(model string) string
- func ExtractCustomHeadersFromMetadata(metadata map[string]any) map[string]string
- func ModelAliasHint(requestedModel string, aliases []string) string
- func NewTransientRefreshError() error
- func NormalizeCredentialPolicy(policy string) (string, bool)
- func NormalizeExplicitID(raw string) string
- func OAuthModelAliasChannel(provider, authKind string) string
- func ProviderRefreshLead(provider string, runtime any) *time.Duration
- func RefreshBlocksDispatch(auth *Auth) bool
- func RefreshRetryBackoffOpen(auth *Auth, now time.Time) bool
- func RegisterRefreshLeadProvider(provider string, factory func() *time.Duration)
- func WithSkipPersist(ctx context.Context) context.Context
- type Auth
- func (a *Auth) AccountInfo() (string, string)
- func (a *Auth) AuthKind() string
- func (a *Auth) Clone() *Auth
- func (a *Auth) DisableCoolingOverride() *bool
- func (a *Auth) EnsureIndex() string
- func (a *Auth) ExpirationTime() (time.Time, bool)
- func (a *Auth) ProxyInfo() string
- func (a *Auth) RecentRequestsSnapshot(now time.Time) []RecentRequestBucket
- func (a *Auth) RequestRetryOverride() (int, bool)
- func (a *Auth) ToolPrefixDisabled() bool
- type CooldownClearResult
- type DispatchDecision
- type Error
- type ExcludedConcurrencyCandidate
- type FileTokenStore
- type FillFirstSelector
- type FullAuthResolver
- type Manager
- func (m *Manager) AliasesForUpstreamModel(requestedModel string, access *ModelAccess) []string
- func (m *Manager) ClearDisabledCooldownStates(ctx context.Context) error
- func (m *Manager) ClearQuotaCooldown(ctx context.Context, credentialID, model string) (CooldownClearResult, error)
- func (m *Manager) Delete(ctx context.Context, id string) error
- func (m *Manager) DescribeModelStates(auth *Auth, modelFilter string, now time.Time) []ModelStateView
- func (m *Manager) Dispatch(ctx context.Context, providers []string, requestedModel string, opts Options) (*DispatchDecision, error)
- func (m *Manager) FenceDisabledCooldownStates(ctx context.Context) error
- func (m *Manager) GetByID(id string) (*Auth, bool)
- func (m *Manager) GetByIndex(index string) (*Auth, bool)
- func (m *Manager) List() []*Auth
- func (m *Manager) MarkResult(ctx context.Context, result Result)
- func (m *Manager) ReconcileRegistryModelStates(_ context.Context, authID string)
- func (m *Manager) RefreshAuthCredential(ctx context.Context, target *Auth) (*Auth, error)
- func (m *Manager) RefreshNow(ctx context.Context, authIndex string) (*Auth, error)
- func (m *Manager) RefreshNowObserved(ctx context.Context, authIndex, observedAccessTokenSHA256 string) (*Auth, error)
- func (m *Manager) RefreshSchedulerEntry(authID string)
- func (m *Manager) Register(ctx context.Context, auth *Auth) (*Auth, error)
- func (m *Manager) ResolveExecutionModel(auth *Auth, routeModel string) string
- func (m *Manager) SetAutoRefreshHandler(handler func(context.Context, *Auth) error)
- func (m *Manager) SetConfig(cfg *internalconfig.Config)
- func (m *Manager) SetFullAuthResolver(resolver FullAuthResolver)
- func (m *Manager) SetModelAliasHints(auth *Auth, publicModels []string)
- func (m *Manager) SetOAuthModelAlias(aliases map[string][]internalconfig.OAuthModelAlias)
- func (m *Manager) SetPluginAuthRefresher(refresher PluginAuthRefresher)
- func (m *Manager) SetPluginScheduler(scheduler PluginScheduler)
- func (m *Manager) SetRoundTripperProvider(p RoundTripperProvider)
- func (m *Manager) SetSelector(selector Selector)
- func (m *Manager) SetStore(store Store)
- func (m *Manager) ShouldRefreshCredential(auth *Auth, now time.Time) bool
- func (m *Manager) Shutdown()
- func (m *Manager) StartAutoRefresh(parent context.Context, interval time.Duration)
- func (m *Manager) StopAutoRefresh()
- func (m *Manager) Update(ctx context.Context, auth *Auth) (*Auth, error)
- type ModelAccess
- type ModelState
- type ModelStateView
- type Options
- type PluginAuthRefresher
- type PluginScheduler
- type PostAuthHook
- type QuotaState
- type RecentRequestBucket
- type RefreshEvaluator
- type Result
- type RoundRobinSelector
- type RoundTripperProvider
- type Selector
- type SessionAffinityCommit
- type SessionAffinityConfig
- type SessionAffinitySelection
- type SessionAffinitySelector
- type SessionAffinityStore
- type SessionBinding
- type SessionCache
- func (c *SessionCache) CompareAndSwapSessionBinding(ctx context.Context, commit SessionAffinityCommit) (bool, error)
- 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) LoadSessionBinding(ctx context.Context, key string) (SessionBinding, error)
- func (c *SessionCache) Set(sessionID, authID string)
- func (c *SessionCache) Stop()
- type StateMutator
- type StateVersionSaver
- type Status
- type StoppableSelector
- type Store
- type UpstreamResponse
- type WeightedRoundRobinSelector
Constants ¶
const ( // CredentialPolicyMetadataKey stores the dispatch credential policy in Options.Metadata. CredentialPolicyMetadataKey = "credential_policy" // CredentialPolicyCodexAlphaSearchV1 selects credentials supported by Codex Alpha Search. CredentialPolicyCodexAlphaSearchV1 = "codex_alpha_search_v1" // AttributeCodexAlphaSearch marks an opted-in Codex API key. AttributeCodexAlphaSearch = "codex_alpha_search" AuthKindAPIKey = "apikey" AuthKindOAuth = "oauth" )
const AllowedAuthIDsMetadataKey = "allowed_auth_ids"
AllowedAuthIDsMetadataKey stores the dispatch allowlist in Options.Metadata.
const AllowedModelIDsMetadataKey = "allowed_model_ids"
AllowedModelIDsMetadataKey stores the model allowlist in Options.Metadata.
const ErrorCodeRefreshOutcomeUnknown = "refresh_outcome_unknown"
ErrorCodeRefreshOutcomeUnknown requires replacement or reconciliation of a refresh grant.
const ErrorCodeRequestScoped = "request_scoped"
ErrorCodeRequestScoped marks failures belonging to one downstream request. They must not change credential or model availability.
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 because of it.
const ExcludedAuthIDsMetadataKey = "excluded_auth_ids"
ExcludedAuthIDsMetadataKey stores credential IDs already attempted for the current request retry round in Options.Metadata.
const ExcludedConcurrencyCandidatesMetadataKey = "excluded_concurrency_candidates"
ExcludedConcurrencyCandidatesMetadataKey stores candidates rejected by atomic concurrency admission during this dispatch attempt.
const RequestRetryRoundMetadataKey = "request_retry_round"
RequestRetryRoundMetadataKey stores the zero-based request retry round in Options.Metadata. Round zero is the initial credential round.
const RequestedModelMetadataKey = "requested_model"
RequestedModelMetadataKey stores the client-requested model name in Options.Metadata. It is used to preserve the original model string across prefix rewriting / alias resolution.
Variables ¶
var ( ErrFullAuthNotFound = errors.New("full auth not found") ErrRefreshUnsupported = &Error{ Code: refreshUnsupportedCode, Message: refreshUnsupportedMsg, HTTPStatus: http.StatusServiceUnavailable, } )
var ErrCooldownMutationUnsupported = errors.New("auth manager: cooldown reset requires an atomic state store")
ErrCooldownMutationUnsupported indicates that the auth store cannot apply an atomic cooldown reset. Home requires atomic mutation so multiple instances sharing one database cannot overwrite each other's credential state.
var ErrRuntimeProjectionPersist = errors.New("auth: cannot persist an incomplete runtime projection")
ErrRuntimeProjectionPersist prevents scheduling projections from replacing complete credentials in any full-record persistence path.
var ErrSessionAffinityConflict = errors.New("session affinity binding changed")
ErrSessionAffinityConflict asks dispatch to re-read a concurrently changed binding.
Functions ¶
func AccessTokenSHA256 ¶ added in v1.0.65
AccessTokenSHA256 fingerprints an OAuth token without exposing it.
func ApplyCustomHeadersFromMetadata ¶
func ApplyCustomHeadersFromMetadata(auth *Auth)
ApplyCustomHeadersFromMetadata updates apply custom headers from metadata.
func ApplyRefreshPendingState ¶ added in v1.0.65
ApplyRefreshPendingState opens refresh-only backoff without changing request availability.
func ApplyRefreshSuccessState ¶ added in v1.0.65
ApplyRefreshSuccessState clears refresh errors and unauthorized execution state.
func ApplyUnsupportedRefreshBackoff ¶ added in v1.0.65
ApplyUnsupportedRefreshBackoff clears credential-level refresh blocking while backing off further refresh attempts for an unsupported credential.
func AuthIsNewerThanObserved ¶ added in v1.0.65
AuthIsNewerThanObserved reports whether Home stores a different access token from the one used by the failed downstream attempt.
func CanUseObservedTokenAfterRefreshFailure ¶ added in v1.0.72
func CanUseObservedTokenAfterRefreshFailure(auth *Auth, observedAccessTokenSHA256 string, errRefresh error, now time.Time) bool
CanUseObservedTokenAfterRefreshFailure reports whether a downstream caller can safely keep using the exact Antigravity token it observed when refresh fails. This compatibility path never accepts terminal or canceled refreshes.
func CanonicalModelID ¶ added in v1.0.62
CanonicalModelID removes a request-option suffix and surrounding whitespace from a model ID.
func ExtractCustomHeadersFromMetadata ¶
ExtractCustomHeadersFromMetadata extracts a custom headers from metadata.
func ModelAliasHint ¶ added in v1.1.8
ModelAliasHint formats the public model IDs for a lookup error message.
func NewTransientRefreshError ¶ added in v1.0.65
func NewTransientRefreshError() error
NewTransientRefreshError returns a generic refresh acquisition error.
func NormalizeCredentialPolicy ¶ added in v1.0.67
NormalizeCredentialPolicy validates and canonicalizes a dispatch credential policy.
func NormalizeExplicitID ¶ added in v1.0.73
NormalizeExplicitID validates and cleans an explicit session identifier. It trims whitespace, rejects control characters, and rejects IDs exceeding 256 bytes.
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).
Supported channels: vertex, antigravity, claude, codex, kimi, xai, meta, devin.
func ProviderRefreshLead ¶
ProviderRefreshLead handles a provider refresh lead.
func RefreshBlocksDispatch ¶ added in v1.0.72
RefreshBlocksDispatch reports whether a credential-level refresh failure must prevent request selection. Unsupported refresh remains refresh-only backoff and must not be promoted to a dispatch block.
func RefreshRetryBackoffOpen ¶ added in v1.0.67
RefreshRetryBackoffOpen reports whether provider refresh calls are currently backed off. This state is intentionally ignored by request selection.
func RegisterRefreshLeadProvider ¶
RegisterRefreshLeadProvider handles a register refresh lead provider.
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 Auth ¶
type Auth struct {
// ID uniquely identifies the auth record across restarts.
ID string `json:"id"`
// 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:"-"`
// 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"`
// 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"`
// RuntimeProjection marks an incomplete scheduling view that must never be
// saved as a complete credential. Full database snapshots leave this false.
RuntimeProjection bool `json:"-"`
// RuntimeDisableCooling carries the auth-scoped cooling override in minimal
// projections without serializing provider metadata or secrets.
RuntimeDisableCooling *bool `json:"-"`
// RuntimeRefreshBlocked preserves a credential-level refresh block in
// minimal projections without copying provider response diagnostics.
RuntimeRefreshBlocked bool `json:"-"`
// 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"`
// LastRefreshError preserves refresh acquisition diagnostics independently
// from ordinary execution results while refresh backoff remains active.
LastRefreshError *Error `json:"last_refresh_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"`
// 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:"-"`
// StateVersion is the storage revision of this runtime snapshot when available.
StateVersion int64 `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 (*Auth) AccountInfo ¶
AccountInfo handles an account info.
func (*Auth) AuthKind ¶ added in v1.0.67
AuthKind returns the explicit credential kind or infers it from the credential shape.
func (*Auth) Clone ¶
Clone copies the Auth structure, duplicating mutable fields to avoid accidental mutation.
func (*Auth) DisableCoolingOverride ¶
DisableCoolingOverride returns the auth-scoped disable_cooling override when present. Runtime projections take precedence over metadata. Metadata is read from "disable_cooling" (or legacy "disable-cooling"). Callers must treat the returned pointer as read-only.
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 credential expiration timestamp from metadata. It inspects common absolute expiry keys, expires_in plus timestamp, and nested token objects to remain compatible with legacy auth file formats.
func (*Auth) RecentRequestsSnapshot ¶
func (a *Auth) RecentRequestsSnapshot(now time.Time) []RecentRequestBucket
RecentRequestsSnapshot handles a recent requests snapshot.
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) 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 CooldownClearResult ¶ added in v1.0.67
type CooldownClearResult struct {
CredentialID string
Model string
Cleared bool
ClearedModels []string
}
CooldownClearResult describes quota cooldown state removed by an operator.
type DispatchDecision ¶
type DispatchDecision struct {
Auth *Auth
Provider string
UpstreamModel string
RequestRetry int
PooledModels bool
ForceMapping bool
OriginalAlias string
}
DispatchDecision captures the scheduler selection for an incoming request.
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"`
// Diagnostic is a redacted internal summary for trusted transports and logs.
Diagnostic string `json:"diagnostic,omitempty"`
// 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"`
// Upstream preserves the provider response independently from internal
// scheduling classification.
Upstream *UpstreamResponse `json:"upstream,omitempty"`
}
Error describes an authentication related failure in a provider agnostic format.
func ApplyRefreshFailureState ¶ added in v1.0.72
ApplyRefreshFailureState backs off credential acquisition after a transient refresh failure. A known-valid Antigravity access token remains dispatchable outside the request safety window while Home retries the refresh.
func (*Error) Is ¶ added in v1.0.72
Is preserves sentinel matching for structured unsupported-refresh errors.
func (*Error) StatusCode ¶
StatusCode returns the HTTP status code.
type ExcludedConcurrencyCandidate ¶ added in v1.0.61
ExcludedConcurrencyCandidate identifies a credential-wide or model-scoped exclusion.
type FileTokenStore ¶
type FileTokenStore struct {
// contains filtered or unexported fields
}
FileTokenStore persists token records and auth metadata using the filesystem as backing storage.
func NewFileTokenStore ¶
func NewFileTokenStore() *FileTokenStore
NewFileTokenStore creates a token store that saves credentials to disk through the TokenStorage implementation embedded in the token record.
func (*FileTokenStore) Delete ¶
func (s *FileTokenStore) Delete(ctx context.Context, id string) error
Delete removes the auth file.
func (*FileTokenStore) List ¶
func (s *FileTokenStore) List(ctx context.Context) ([]*Auth, error)
List enumerates all auth JSON files under the configured directory.
func (*FileTokenStore) Save ¶
Save persists token storage and metadata to the resolved auth file path.
func (*FileTokenStore) SetBaseDir ¶
func (s *FileTokenStore) SetBaseDir(dir string)
SetBaseDir updates the default directory used for auth JSON persistence when no explicit path is provided.
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 FullAuthResolver ¶ added in v1.0.2
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager orchestrates auth lifecycle, selection, and persistence for CLIProxyAPIHome.
This is intentionally narrower than CPA's full execution manager: it only supports registering/updating auths, scheduling selection (Dispatch), and background refresh.
func NewManager ¶
NewManager creates a new manager.
func (*Manager) AliasesForUpstreamModel ¶ added in v1.1.8
func (m *Manager) AliasesForUpstreamModel(requestedModel string, access *ModelAccess) []string
AliasesForUpstreamModel returns only published aliases visible to the caller. Permissions are checked before deduplication and truncation, using each target alias's model-specific channel scope rather than the requested ID's.
func (*Manager) ClearDisabledCooldownStates ¶ added in v1.0.69
ClearDisabledCooldownStates clears request-error and quota cooldown state covered by the global or auth-scoped disable-cooling setting. Cluster-backed stores are mutated through StateMutator so the persisted row remains authoritative across Home nodes.
func (*Manager) ClearQuotaCooldown ¶ added in v1.0.67
func (m *Manager) ClearQuotaCooldown(ctx context.Context, credentialID, model string) (CooldownClearResult, error)
ClearQuotaCooldown atomically clears model quota cooldown state for one credential. An empty model clears every model; a non-empty model clears only that canonical model key.
func (*Manager) DescribeModelStates ¶ added in v1.1.1
func (m *Manager) DescribeModelStates(auth *Auth, modelFilter string, now time.Time) []ModelStateView
DescribeModelStates reads one auth snapshot without selecting credentials or changing state. Registered route models resolve through the same prefix and alias pipeline as Dispatch. Unregistered historical keys are opaque state identifiers and are not aliased again.
func (*Manager) Dispatch ¶
func (m *Manager) Dispatch(ctx context.Context, providers []string, requestedModel string, opts Options) (*DispatchDecision, error)
Dispatch processes dispatch.
func (*Manager) FenceDisabledCooldownStates ¶ added in v1.0.69
FenceDisabledCooldownStates clears covered cooldown state and advances the revision of auths with queued result snapshots or a prior failed cleanup. It is used when global disable-cooling changes so older asynchronous snapshots cannot restore a cooldown after the configuration switch.
func (*Manager) GetByIndex ¶
GetByIndex returns a by index.
func (*Manager) MarkResult ¶
MarkResult records a downstream execution result and updates auth cooldown state.
func (*Manager) ReconcileRegistryModelStates ¶
ReconcileRegistryModelStates aligns the derived model registry with the authoritative scheduler state held by this Home instance.
func (*Manager) RefreshAuthCredential ¶ added in v1.0.2
RefreshAuthCredential refreshes a full auth value without updating memory or persistence.
func (*Manager) RefreshNow ¶
RefreshNow forces a best-effort credential refresh for the given auth. It updates the in-memory record and persists it when enabled.
func (*Manager) RefreshNowObserved ¶ added in v1.0.65
func (m *Manager) RefreshNowObserved(ctx context.Context, authIndex, observedAccessTokenSHA256 string) (*Auth, error)
RefreshNowObserved refreshes unless Home already replaced the access token observed by the downstream attempt that received a 401.
func (*Manager) RefreshSchedulerEntry ¶
RefreshSchedulerEntry refreshes refresh scheduler entry.
func (*Manager) ResolveExecutionModel ¶ added in v1.1.1
ResolveExecutionModel returns the auth-specific upstream model that dispatch would send for a public route model, or the trimmed route model when no alias applies.
func (*Manager) SetAutoRefreshHandler ¶ added in v1.0.65
SetAutoRefreshHandler routes background refresh through the cluster lock owner.
func (*Manager) SetConfig ¶
func (m *Manager) SetConfig(cfg *internalconfig.Config)
SetConfig sets a config.
func (*Manager) SetFullAuthResolver ¶ added in v1.0.2
func (m *Manager) SetFullAuthResolver(resolver FullAuthResolver)
SetFullAuthResolver sets a full auth resolver.
func (*Manager) SetModelAliasHints ¶ added in v1.1.8
SetModelAliasHints indexes the effective upstream models behind published public model IDs, including OAuth aliases and credential prefixes. Passing no public models removes this credential's hints.
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) SetPluginAuthRefresher ¶ added in v1.0.39
func (m *Manager) SetPluginAuthRefresher(refresher PluginAuthRefresher)
SetPluginAuthRefresher sets the optional plugin auth refresher.
func (*Manager) SetPluginScheduler ¶ added in v1.0.39
func (m *Manager) SetPluginScheduler(scheduler PluginScheduler)
SetPluginScheduler sets the optional plugin scheduler.
func (*Manager) SetRoundTripperProvider ¶
func (m *Manager) SetRoundTripperProvider(p RoundTripperProvider)
SetRoundTripperProvider sets a round tripper provider.
func (*Manager) SetSelector ¶
SetSelector sets a selector.
func (*Manager) ShouldRefreshCredential ¶ added in v1.0.56
ShouldRefreshCredential reports whether the credential is due for refresh.
func (*Manager) Shutdown ¶ added in v1.0.2
func (m *Manager) Shutdown()
Shutdown stops background auth work and releases selector resources.
func (*Manager) StartAutoRefresh ¶
StartAutoRefresh starts an auto refresh.
func (*Manager) StopAutoRefresh ¶
func (m *Manager) StopAutoRefresh()
StopAutoRefresh stops an auto refresh.
type ModelAccess ¶ added in v1.1.3
type ModelAccess struct {
// contains filtered or unexported fields
}
ModelAccess is a read-only credential/model policy for catalog enumeration. Nil sets are unrestricted; non-nil empty sets deny all access. It deliberately excludes transient scheduling and concurrency state.
func NewModelAccess ¶ added in v1.1.3
func NewModelAccess(authIDs, modelIDs []string, modelAuthIDs map[string][]string) *ModelAccess
NewModelAccess normalizes catalog restrictions using the dispatch filters. Model-specific credential sets are intersected with the base credential set.
func (*ModelAccess) Allows ¶ added in v1.1.3
func (a *ModelAccess) Allows(authID, modelID string) bool
Allows reports whether a credential may expose this public model ID. A nil policy preserves the unscoped catalog used outside database-backed Home.
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"`
// QuotaResetAt marks an operator reset so peers can merge it without
// discarding unrelated local execution errors.
QuotaResetAt time.Time `json:"quota_reset_at,omitzero"`
}
ModelState captures the execution state for a specific model under an auth entry.
func MergePersistedModelState ¶ added in v1.0.67
func MergePersistedModelState(persistedState, localState *ModelState) *ModelState
MergePersistedModelState combines authoritative persisted quota state with newer execution-only state accumulated by one Home instance.
func (*ModelState) Clone ¶
func (m *ModelState) Clone() *ModelState
Clone duplicates a model state including nested error details.
type ModelStateView ¶ added in v1.1.1
type ModelStateView struct {
Model string
UpstreamModel string
StateKey string
DisplayName string
Registered bool
State *ModelState
Blocked bool
BlockReason string
NextRetryAfter time.Time
}
ModelStateView pairs recorded execution state with effective scheduling availability. State is diagnostic history; Blocked and NextRetryAfter apply the current cooling policy.
type Options ¶
type Options struct {
Headers http.Header
Query url.Values
OriginalRequest []byte
Metadata map[string]any
SessionAffinity *SessionAffinitySelection
}
Options carries optional request hints used during dispatch selection.
This is a deliberately small subset of CPA's execution options: CLIProxyAPIHome only needs headers / query / raw request bytes for selector decisions, and a generic metadata bag.
type PluginAuthRefresher ¶ added in v1.0.39
PluginAuthRefresher lets provider plugins refresh Home-owned auth records.
type PluginScheduler ¶ added in v1.0.39
type PluginScheduler interface {
PickAuth(context.Context, pluginapi.SchedulerPickRequest) (pluginapi.SchedulerPickResponse, bool, error)
}
PluginScheduler lets scheduler plugins select from Home-filtered auth candidates.
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 QuotaState ¶
type QuotaState struct {
// Exceeded indicates the credential recently hit a quota error.
Exceeded bool `json:"exceeded"`
// Scope records that this quota is model-scoped or aggregated from models.
Scope string `json:"scope,omitempty"`
// 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"`
}
QuotaState contains limiter tracking data for a credential.
type RecentRequestBucket ¶
type RefreshEvaluator ¶
RefreshEvaluator allows runtime state to override refresh decisions.
type Result ¶
type Result struct {
AuthID string
AuthIndex string
Provider string
Model string
Success bool
Error *Error
RetryAfter *time.Duration
ResetAt *time.Time
AccessTokenSHA256 string
}
Result captures an upstream execution result reported by a downstream CPA node.
func NewUsageResult ¶
NewUsageResult creates a new usage result.
func NewUsageResultWithCode ¶ added in v1.1.8
func NewUsageResultWithCode(authIndex, provider, model string, statusCode int, body string, code string) Result
NewUsageResultWithCode creates a usage result carrying a structured failure classification (e.g. ErrorCodeStreamTruncated) reported by the downstream.
type RoundRobinSelector ¶
type RoundRobinSelector struct {
// contains filtered or unexported fields
}
RoundRobinSelector provides a simple provider scoped round-robin selection strategy.
type RoundTripperProvider ¶
type RoundTripperProvider interface {
RoundTripperFor(auth *Auth) http.RoundTripper
}
RoundTripperProvider defines a minimal provider of per-auth HTTP transports.
type Selector ¶
type Selector interface {
Pick(ctx context.Context, provider, model string, opts Options, auths []*Auth) (*Auth, error)
}
Selector chooses an auth candidate for dispatch.
type SessionAffinityCommit ¶ added in v1.1.6
type SessionAffinityCommit struct {
Key string
ExpectedRevision string
// ExpiredAt guards a cold selection based on an expired snapshot against
// a concurrent renewal that keeps the same credential revision.
ExpiredAt time.Time
AuthID string
TTL time.Duration
}
SessionAffinityCommit conditionally renews or replaces a binding.
type SessionAffinityConfig ¶
type SessionAffinityConfig struct {
Fallback Selector
TTL time.Duration
Store SessionAffinityStore
}
SessionAffinityConfig configures the session affinity selector.
type SessionAffinitySelection ¶ added in v1.1.6
type SessionAffinitySelection struct {
Store SessionAffinityStore
Commit *SessionAffinityCommit
}
SessionAffinitySelection defers binding changes until dispatch is prepared and admitted. Each dispatch attempt owns its selection; selectors must not share it.
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 NewSessionAffinitySelectorWithConfig ¶
func NewSessionAffinitySelectorWithConfig(cfg SessionAffinityConfig) *SessionAffinitySelector
NewSessionAffinitySelectorWithConfig creates a selector with custom configuration.
func (*SessionAffinitySelector) InvalidateAuth ¶
func (s *SessionAffinitySelector) InvalidateAuth(authID string)
InvalidateAuth removes local bindings when a credential is removed. Shared bindings are revalidated against each request's candidates and replaced by CAS, so a delayed node-local invalidation cannot delete a newer cluster binding.
func (*SessionAffinitySelector) Pick ¶
func (s *SessionAffinitySelector) Pick(ctx context.Context, provider, model string, opts Options, auths []*Auth) (*Auth, error)
Pick selects an auth with session affinity when possible. Priority for session ID extraction:
- Anthropic / Claude Code headers (X-Claude-Code-Session-Id, X-Claude-Code-Agent-Id)
- Claude Code metadata.user_id in payload (user_xxx_account__session_xxx)
- OpenAI / Codex CLI headers (Session-Id, Session_id, X-Codex-Parent-Thread-Id)
- Antigravity CLI headers (X-Http-Session-Id)
- Explicit session headers (X-Session-ID, X-Session-Affinity, X-Slot-Session-Id)
- Conversation / Client headers (X-Conversation-Id, X-Thread-Id, X-Client-Request-Id)
- Body session_id / sessionId (root or nested request)
- Body metadata.user_id (non-Claude Code format)
- Body conversation_id
- Hash-based fallback from message content
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.
type SessionAffinityStore ¶ added in v1.1.6
type SessionAffinityStore interface {
LoadSessionBinding(context.Context, string) (SessionBinding, error)
CompareAndSwapSessionBinding(context.Context, SessionAffinityCommit) (bool, error)
}
SessionAffinityStore provides authoritative reads and atomic conditional writes. A missing binding has an empty revision. Expired bindings retain their revision until deleted so stale writers cannot overwrite a newer binding.
type SessionBinding ¶ added in v1.1.6
SessionBinding is an authoritative snapshot, including expired bindings. Revisions are opaque and must never be reused after deletion or expiration.
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 (*SessionCache) CompareAndSwapSessionBinding ¶ added in v1.1.6
func (c *SessionCache) CompareAndSwapSessionBinding(ctx context.Context, commit SessionAffinityCommit) (bool, error)
CompareAndSwapSessionBinding prevents concurrent first requests from returning independently selected credentials, including after a binding has been evicted.
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 TTL on hit. This extends the binding lifetime for active sessions.
func (*SessionCache) Invalidate ¶
func (c *SessionCache) Invalidate(sessionID string)
Invalidate removes a specific session binding.
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) LoadSessionBinding ¶ added in v1.1.6
func (c *SessionCache) LoadSessionBinding(ctx context.Context, key string) (SessionBinding, error)
LoadSessionBinding implements the atomic binding store for standalone selectors.
func (*SessionCache) Set ¶
func (c *SessionCache) Set(sessionID, authID string)
Set binds a session to an auth ID with TTL refresh.
func (*SessionCache) Stop ¶
func (c *SessionCache) Stop()
Stop terminates the background cleanup goroutine safely and idempotently.
type StateMutator ¶ added in v1.0.49
type StateMutator interface {
MutateAuthState(ctx context.Context, id string, mutate func(auth *Auth) bool) (*Auth, error)
}
StateMutator is an optional Store capability. Implementations load the authoritative persisted copy of the auth (typically under a database row lock), apply mutate to it, and persist the result atomically when mutate reports a change. The returned auth reflects the post-mutation persisted state whether or not anything changed. Backends that implement this interface let availability transitions such as quota backoff escalation stay atomic across multiple Home nodes sharing one database.
type StateVersionSaver ¶ added in v1.0.67
type StateVersionSaver interface {
SaveWithStateVersion(ctx context.Context, auth *Auth) (id string, stateVersion int64, err error)
}
StateVersionSaver is an optional Store capability that returns the revision accepted for a save. A zero revision means the snapshot was ignored as stale.
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.
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.
func GetTokenStore ¶
func GetTokenStore() Store
GetTokenStore returns the globally registered token store.
type UpstreamResponse ¶ added in v1.0.72
UpstreamResponse contains the exact HTTP response returned by a provider.
type WeightedRoundRobinSelector ¶ added in v1.0.75
type WeightedRoundRobinSelector struct {
// contains filtered or unexported fields
}
WeightedRoundRobinSelector provides smooth weighted round-robin selection.
Source Files
¶
- auto_refresh_loop.go
- cooldown.go
- credential_policy.go
- custom_headers.go
- dispatch.go
- dispatch_filter.go
- errors.go
- filestore.go
- interfaces.go
- manager.go
- model_access.go
- model_alias_apikey.go
- model_alias_hint.go
- model_states.go
- model_suffix.go
- oauth_model_alias.go
- options.go
- persist_policy.go
- plugin_hooks.go
- refresh.go
- refresh_registry.go
- result.go
- scheduler.go
- selector.go
- selector_weighted.go
- session_affinity_store.go
- session_cache.go
- status.go
- store.go
- store_registry.go
- types.go