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 AuthIsNewerThanObserved(auth *Auth, observedAccessTokenSHA256 string) bool
- func CanonicalModelID(model string) string
- func ExtractCustomHeadersFromMetadata(metadata map[string]any) map[string]string
- func NewTransientRefreshError() error
- func NormalizeCredentialPolicy(policy string) (string, bool)
- func OAuthModelAliasChannel(provider, authKind string) string
- func ProviderRefreshLead(provider string, runtime any) *time.Duration
- 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) 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) 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) SetAutoRefreshHandler(handler func(context.Context, *Auth) error)
- func (m *Manager) SetConfig(cfg *internalconfig.Config)
- func (m *Manager) SetFullAuthResolver(resolver FullAuthResolver)
- 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 ModelState
- type Options
- type PluginAuthRefresher
- type PluginScheduler
- type PostAuthHook
- type QuotaState
- type RecentRequestBucket
- type RefreshEvaluator
- type Result
- type RoundRobinSelector
- type RoundTripperProvider
- type Selector
- type SessionAffinityConfig
- type SessionAffinitySelector
- type SessionCache
- 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) Set(sessionID, authID string)
- func (c *SessionCache) Stop()
- type StateMutator
- type StateVersionSaver
- type Status
- type StoppableSelector
- type Store
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 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.
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 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 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 NewTransientRefreshError ¶ added in v1.0.65
func NewTransientRefreshError() error
NewTransientRefreshError returns a redacted refresh acquisition error.
func NormalizeCredentialPolicy ¶ added in v1.0.67
NormalizeCredentialPolicy validates and canonicalizes a dispatch credential policy.
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.
func ProviderRefreshLead ¶
ProviderRefreshLead handles a provider refresh lead.
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"`
// RuntimeDisableCooling carries the auth-scoped cooling override in minimal
// projections without serializing provider metadata or secrets.
RuntimeDisableCooling *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"`
// 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 keys such as "expired", "expire", "expires_at", and also 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"`
// 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"`
}
Error describes an authentication related failure in a provider agnostic format.
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) 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) 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) 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) 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) StartAutoRefresh ¶
StartAutoRefresh starts an auto refresh.
func (*Manager) StopAutoRefresh ¶
func (m *Manager) StopAutoRefresh()
StopAutoRefresh stops an auto refresh.
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 Options ¶
type Options struct {
Headers http.Header
Query url.Values
OriginalRequest []byte
Metadata map[string]any
}
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
AccessTokenSHA256 string
}
Result captures an upstream execution result reported by a downstream CPA node.
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 SessionAffinityConfig ¶
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 NewSessionAffinitySelectorWithConfig ¶
func NewSessionAffinitySelectorWithConfig(cfg SessionAffinityConfig) *SessionAffinitySelector
NewSessionAffinitySelectorWithConfig creates a selector with custom configuration.
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) 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:
- metadata.user_id (Claude Code format with _session_{uuid}) - highest priority
- X-Session-ID header
- Session_id header (Codex)
- X-Client-Request-Id header (PI)
- metadata.user_id (non-Claude Code format)
- conversation_id field in request body
- Stable hash from first few messages content (fallback)
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 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) 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) 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.
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.
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_alias_apikey.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
- session_cache.go
- status.go
- store.go
- store_registry.go
- types.go