auth

package
v8.0.73 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 57 Imported by: 2

Documentation

Index

Constants

View Source
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"
)
View Source
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__"
)
View Source
const (
	RequestScopedActionStop                = "stop"
	RequestScopedActionStopAndCooldown     = "stop-and-cooldown"
	RequestScopedActionContinue            = "continue"
	RequestScopedActionContinueAndCooldown = "continue-and-cooldown"
)

Request-scoped error actions.

View Source
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"
)
View Source
const (
	AttributeAuthIndexSeed = "auth_index_seed"
	AttributePluginVirtual = "plugin_virtual"
	AttributeVirtualSource = "virtual_source"
)
View 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"
)
View Source
const AntigravityCreditsHintRefreshInterval = 10 * time.Minute

AntigravityCreditsHintRefreshInterval defines how long a cached AI credits hint remains fresh before it should be re-validated.

View Source
const AttributeFilePriority = "file_priority"

AttributeFilePriority marks priority values inherited from a physical auth file.

View Source
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.

View Source
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).

View Source
const (
	// CredentialPolicyCodexAlphaSearchV1 selects credentials supported by Codex Alpha Search.
	CredentialPolicyCodexAlphaSearchV1 = "codex_alpha_search_v1"
)
View Source
const ErrorCodeConnectionLifecycle = "connection_lifecycle"

ErrorCodeConnectionLifecycle marks transport/session lifecycle failures that must skip credential cooldown without being treated as request-scoped faults.

View Source
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.

View Source
const ErrorCodeForceCooldown = "force_cooldown"

ErrorCodeForceCooldown marks failures that must enforce credential cooldown.

View Source
const ErrorCodeRequestScoped = "request_scoped"

ErrorCodeRequestScoped identifies failures tied to the current request rather than the selected credential.

View Source
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.

View Source
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.

View Source
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

View Source
var ErrMalformedHomeConcurrencyTuple = errors.New("malformed Home concurrency tuple")

Functions

func AccessTokenSHA256

func AccessTokenSHA256(auth *Auth) string

AccessTokenSHA256 returns the normalized OAuth access-token fingerprint used to fence asynchronous Home execution results without exposing the token.

func AntigravityCreditsRequested

func AntigravityCreditsRequested(ctx context.Context) bool

AntigravityCreditsRequested reports whether the context carries the credits flag.

func ApplyAuthPriorityMetadata

func ApplyAuthPriorityMetadata(auth *Auth, metadata map[string]any)

ApplyAuthPriorityMetadata copies a valid file priority into an auth's metadata and routing attributes.

func ApplyAuthWeightMetadata

func ApplyAuthWeightMetadata(auth *Auth, metadata map[string]any) error

ApplyAuthWeightMetadata validates the auth and applies a source metadata weight.

func ApplyCustomHeadersFromMetadata

func ApplyCustomHeadersFromMetadata(auth *Auth)

func AuthGrantFingerprint added in v8.0.48

func AuthGrantFingerprint(a *Auth) string

AuthGrantFingerprint computes a SHA-256 fingerprint of the credential's token grant and account identity.

func CanonicalCredentialMetadataKey

func CanonicalCredentialMetadataKey(key string) string

CanonicalCredentialMetadataKey returns the canonical snake_case name for credential metadata keys that previously also accepted config-style aliases.

func CanonicalSessionID

func CanonicalSessionID(headers http.Header, payload []byte, metadata map[string]any) string

CanonicalSessionID resolves the single authoritative session identity from request options and metadata.

func ClearUnauthorizedModelStates

func ClearUnauthorizedModelStates(auth *Auth, now time.Time) []string

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

func CredentialsChanged(existing, incoming *Auth) bool

CredentialsChanged reports whether authentication credentials (tokens or API keys) differ between two Auth records.

func ExtractCustomHeadersFromMetadata

func ExtractCustomHeadersFromMetadata(metadata map[string]any) map[string]string

func ExtractSessionID

func ExtractSessionID(headers http.Header, payload []byte, metadata map[string]any) string

ExtractSessionID extracts a session identifier from explicit client signals, then falls back to execution metadata, derived identity, and message history. Priority order:

  1. X-Claude-Code-Session-Id
  2. Claude Code metadata.user_id session
  3. Session-Id / Session_id (Codex and compatible clients)
  4. X-Session-ID
  5. X-Session-Affinity (OpenCode)
  6. X-Client-Request-Id (pi Responses)
  7. session_id / sessionId
  8. prompt_cache_key, with conversation / conversation.id as an alias
  9. metadata.user_id and conversation_id legacy body fields
  10. explicit execution session metadata
  11. stable context-derived session identity
  12. stable hash from initial message content

func ExtractUpstreamErrorSummary

func ExtractUpstreamErrorSummary(raw string) string

ExtractUpstreamErrorSummary extracts and sanitizes a concise error summary from upstream error strings.

func HasAuthCreationIntent

func HasAuthCreationIntent(ctx context.Context) bool

HasAuthCreationIntent reports whether the current save is part of a login or credential migration flow that may intentionally create a disabled record.

func HasDisabledInvalidGrantFailure

func HasDisabledInvalidGrantFailure(auth *Auth) bool

HasDisabledInvalidGrantFailure reports whether the auth is disabled and has encountered an invalid_grant error.

func HasKnownAntigravityCreditsHint

func HasKnownAntigravityCreditsHint(authID string) bool

HasKnownAntigravityCreditsHint reports whether credits state has been discovered for an auth.

func HasTrustedRetryDeadline added in v8.0.45

func HasTrustedRetryDeadline(err error) bool

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

func HasUnauthorizedAuthFailure(auth *Auth) bool

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

func IsAuthAvailableForModel(auth *Auth, model string, now time.Time) bool

IsAuthAvailableForModel reports whether auth is eligible for selection on model at now.

func IsAuthTokenPayloadKey

func IsAuthTokenPayloadKey(key string) bool

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

func IsCodexAuthRecord(auth *Auth) bool

IsCodexAuthRecord reports whether auth represents a Codex credential record.

func IsCodexClientRequest added in v8.0.40

func IsCodexClientRequest(ctx context.Context, clientHeaders ...http.Header) bool

IsCodexClientRequest reports whether the request originates from a Codex client.

func IsCodexClientUserAgent added in v8.0.40

func IsCodexClientUserAgent(userAgent string) bool

IsCodexClientUserAgent reports whether userAgent identifies a Codex client.

func IsCodexUseSIWC added in v8.0.25

func IsCodexUseSIWC(a *Auth) bool

IsCodexUseSIWC reports whether a Codex auth record is configured to use its nested "siwc" section.

func IsCodexUseSIWCForRequest added in v8.0.40

func IsCodexUseSIWCForRequest(ctx context.Context, a *Auth, clientHeaders ...http.Header) bool

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

func IsConfigAPIKeyAuth(auth *Auth) bool

IsConfigAPIKeyAuth reports whether the auth entry is synthesized from config *-api-key lists.

func IsForceRefreshContext added in v8.0.25

func IsForceRefreshContext(ctx context.Context) bool

IsForceRefreshContext reports whether ctx carries an explicit forced credential refresh marker.

func IsPluginVirtualAuth

func IsPluginVirtualAuth(auth *Auth) bool

IsPluginVirtualAuth reports whether an auth was expanded from a plugin-owned source file.

func IsTerminalAuthError

func IsTerminalAuthError(err error) bool

IsTerminalAuthError checks if err or any error in its chain represents a permanent upstream auth failure.

func MarkPluginVirtualAuth

func MarkPluginVirtualAuth(auth *Auth, sourcePath string, ordinal int)

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

func MergeExistingAuthMetadata(target *Auth, existingMap map[string]any)

MergeExistingAuthMetadata merges user-configured metadata fields from existingMap into target.Metadata and target.Storage if target does not already define them.

func NewHomeConcurrencyBusyError

func NewHomeConcurrencyBusyError(message string, retryAfter time.Duration) error

NewHomeConcurrencyBusyError creates a typed Home concurrency busy error.

func NewModelCooldownError

func NewModelCooldownError(model, provider string, resetIn time.Duration) error

NewModelCooldownError creates an error representing model-level cooldown.

func NewTerminalAuthError

func NewTerminalAuthError(err *Error, cause error) error

NewTerminalAuthError wraps an *Error and cause as a terminal upstream authentication failure.

func NormalizeCredentialMetadata

func NormalizeCredentialMetadata(metadata map[string]any)

NormalizeCredentialMetadata rewrites recognized legacy keys to their canonical snake_case names. An explicitly present canonical value wins.

func NotifyAccessTokenFingerprint

func NotifyAccessTokenFingerprint(ctx context.Context, auth *Auth)

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

func OAuthGrantFingerprint(accessToken, refreshToken, email, accountID string) string

OAuthGrantFingerprint computes a SHA-256 fingerprint of an OAuth grant's tokens and account identity.

func OAuthModelAliasChannel

func OAuthModelAliasChannel(provider, authKind string) string

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

func PersistCodexAuthFile(ctx context.Context, path string, auth *Auth) (bool, error)

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 ProviderRefreshLead

func ProviderRefreshLead(provider string, runtime any) *time.Duration

func ProviderSupportsQuotaObservation

func ProviderSupportsQuotaObservation(provider string) bool

ProviderSupportsQuotaObservation reports whether the named provider emits a passive credential-level quota snapshot understood by collectQuotaSignals.

func QuotaCooldownDisabledForAuth

func QuotaCooldownDisabledForAuth(auth *Auth) bool

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 RegisterRefreshLeadProvider

func RegisterRefreshLeadProvider(provider string, factory func() *time.Duration)

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

func SafeResponseHeaders(err error) http.Header

SafeResponseHeaders returns trusted response headers only for concrete retry/cooldown errors.

func SanitizeRenewalMessage added in v8.0.48

func SanitizeRenewalMessage(raw string) string

SanitizeRenewalMessage strips URLs, bearer tokens, JWTs, OAuth codes/states, and secret fields from diagnostic messages.

func SanitizeUpstreamErrorSummary

func SanitizeUpstreamErrorSummary(s string) string

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

func ValidateAuthWeight(auth *Auth) error

ValidateAuthWeight validates every explicit credential weight source.

func WithAntigravityCredits

func WithAntigravityCredits(ctx context.Context) context.Context

WithAntigravityCredits returns a child context that signals the executor to inject enabledCreditTypes into the request payload.

func WithAuthCreationIntent

func WithAuthCreationIntent(ctx context.Context) context.Context

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

func WithCause(err *Error, cause error) error

WithCause wraps an *Error with an underlying cause without changing the Error struct layout.

func WithCodexClientRequest added in v8.0.45

func WithCodexClientRequest(ctx context.Context, isCodexClient bool) context.Context

WithCodexClientRequest stores the resolved Codex client detection flag in ctx so asynchronous post-request paths do not read a reused gin.Context.

func WithDeferredAPIKeyModelAliasRebuild

func WithDeferredAPIKeyModelAliasRebuild(ctx context.Context) context.Context

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

func WithForceRefresh(ctx context.Context) context.Context

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

func WithRequestScopedErrorConfig(ctx context.Context, cfg *internalconfig.Config) context.Context

WithRequestScopedErrorConfig stores the runtime config snapshot on ctx so usage reporters can evaluate request-scoped error rules when publishing attempt failures.

func WithSkipPersist

func WithSkipPersist(ctx context.Context) context.Context

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.

func WithoutSkipPersist added in v8.0.24

func WithoutSkipPersist(ctx context.Context) context.Context

WithoutSkipPersist returns a derived context that re-enables persistence even when the parent context was marked with WithSkipPersist.

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 flags transient provider unavailability (e.g. quota exceeded).
	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

func MergePreparedAuth(base, current, updated *Auth) *Auth

MergePreparedAuth merges prepared request auth updates into current without modifying refresh lifecycle fields (such as LastRefreshedAt, LastError, or cooldown status).

func MergeRefreshedAuth

func MergeRefreshedAuth(base, current, updated *Auth) *Auth

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

func (a *Auth) AccessTokenExpirationTime() (time.Time, bool)

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 (a *Auth) AccountInfo() (string, string)

func (*Auth) AuthKind

func (a *Auth) AuthKind() string

AuthKind returns the credential kind using explicit metadata first and legacy field-shape fallbacks second.

func (*Auth) AuthSourceKind

func (a *Auth) AuthSourceKind() string

AuthSourceKind returns where the Auth entry came from at runtime.

func (*Auth) BindFileSnapshot added in v8.0.33

func (a *Auth) BindFileSnapshot(path string, data []byte)

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

func (a *Auth) Clone() *Auth

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

func (a *Auth) DisableCoolingOverride() (bool, bool)

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

func (a *Auth) EnsureIndex() string

EnsureIndex returns a stable index derived from the auth file name or credential identity.

func (*Auth) ExpirationTime

func (a *Auth) ExpirationTime() (time.Time, bool)

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

func (a *Auth) FileSnapshotMatchesDisk() bool

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

func (a *Auth) FileSnapshotPath() string

FileSnapshotPath returns the backing file path bound to this file snapshot.

func (*Auth) HasFileSnapshot added in v8.0.33

func (a *Auth) HasFileSnapshot() bool

HasFileSnapshot reports whether this Auth is an unversioned file-synthesized snapshot bound to a specific file observation digest.

func (*Auth) HasValidAccessToken

func (a *Auth) HasValidAccessToken(now time.Time) bool

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

func (a *Auth) OuterAccessTokenExpirationTime() (time.Time, bool)

OuterAccessTokenExpirationTime returns the expiration time of the outer access_token, ignoring the nested "siwc" section.

func (*Auth) OuterExpirationTime added in v8.0.25

func (a *Auth) OuterExpirationTime() (time.Time, bool)

OuterExpirationTime extracts the outer credential expiration timestamp, ignoring the nested "siwc" section.

func (*Auth) ProxyInfo

func (a *Auth) ProxyInfo() string

func (*Auth) RecentRequestsSnapshot

func (a *Auth) RecentRequestsSnapshot(now time.Time) []RecentRequestBucket

func (*Auth) RecoveryStageAt added in v8.0.48

func (a *Auth) RecoveryStageAt(now time.Time) string

RecoveryStageAt returns the structured post-login / runtime adoption and verification stage at the given time.

func (*Auth) RenewalStateAt added in v8.0.48

func (a *Auth) RenewalStateAt(now time.Time) string

RenewalStateAt returns the structured renewal lifecycle state at the given time.

func (*Auth) RequestRetryOverride

func (a *Auth) RequestRetryOverride() (int, bool)

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

func (a *Auth) SIWCEarliestRefreshTime() (time.Time, bool)

SIWCEarliestRefreshTime returns the server's lower bound for SIWC token renewal.

func (*Auth) SIWCExpirationTime added in v8.0.25

func (a *Auth) SIWCExpirationTime() (time.Time, bool)

SIWCExpirationTime extracts the expiration timestamp from the nested "siwc" metadata section.

func (*Auth) SIWCRealExpirationTime added in v8.0.37

func (a *Auth) SIWCRealExpirationTime() (time.Time, bool)

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

func (a *Auth) SameFileSnapshot(other *Auth) bool

SameFileSnapshot reports whether two unversioned file snapshots observed the same canonical file content.

func (*Auth) ToolPrefixDisabled

func (a *Auth) ToolPrefixDisabled() bool

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

func NewRequestScopedError(message string, httpStatus int) *Error

NewRequestScopedError creates an Error explicitly flagged as request-scoped so that credential cooldown is skipped.

func ResultErrorFromError added in v8.0.70

func ResultErrorFromError(err error) *Error

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

func (e *Error) Clone() *Error

Clone returns an independent copy of the error, deep-copying the Metadata map so snapshots cannot share mutable state with the original.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) ErrorCode added in v8.0.57

func (e *Error) ErrorCode() string

ErrorCode returns the machine-readable error code embedded in the Error.

func (*Error) IsRequestScoped

func (e *Error) IsRequestScoped() bool

IsRequestScoped reports whether the failure is tied to the current request rather than the selected credential.

func (*Error) MarkRequestScoped

func (e *Error) MarkRequestScoped() *Error

MarkRequestScoped marks the error as request-scoped in place and returns it.

func (*Error) StatusCode

func (e *Error) StatusCode() int

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 {
	SharesExecutionSessionsWith(other ProviderExecutor) bool
}

ExecutionSessionSharer reports whether a replaced executor shares its execution session store with the replacement executor so active sessions stay open.

type ExecutorUnwrapper added in v8.0.73

type ExecutorUnwrapper interface {
	Unwrap() ProviderExecutor
}

ExecutorUnwrapper exposes the underlying executor for wrappers so reuse and session-lifecycle decisions can consult the service-owned executor even when a wrapper hides its concrete type. Wrappers should return their immediate inner executor; the manager follows the chain.

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

Load reads all cooldown state files. A missing directory is treated as empty state.

func (*FileCooldownStateStore) Save

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).

func (*FillFirstSelector) Pick

func (s *FillFirstSelector) Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, auths []*Auth) (*Auth, error)

Pick selects the first available auth for the provider in a deterministic manner.

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

func NewManager(store Store, selector Selector, hook Hook) *Manager

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

func (m *Manager) AvailableProviders() []string

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

func (m *Manager) CloseExecutionSession(sessionID string)

CloseExecutionSession asks all registered executors to release the supplied execution session.

func (*Manager) Execute

func (*Manager) ExecuteCount

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) ExecutorRevision added in v8.0.73

func (m *Manager) ExecutorRevision(provider string) uint64

ExecutorRevision returns the monotonic revision for a provider's executor registration. Each RegisterExecutor and UnregisterExecutor advances it.

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

func (m *Manager) ForceRefreshAuth(ctx context.Context, id string) (*Auth, error)

ForceRefreshAuth triggers an immediate synchronous refresh for the credential.

func (*Manager) GetByID

func (m *Manager) GetByID(id string) (*Auth, bool)

GetByID retrieves an auth entry by its ID.

func (*Manager) GetExecutionSessionAuthByID

func (m *Manager) GetExecutionSessionAuthByID(sessionID string, authID string) (*Auth, bool)

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

func (m *Manager) HasProviderAuth(provider string) bool

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

func (m *Manager) HomeEnabled() bool

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

func (m *Manager) InjectCredentials(req *http.Request, authID string) error

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) List

func (m *Manager) List() []*Auth

List returns all auth entries currently known by the manager.

func (*Manager) Load

func (m *Manager) Load(ctx context.Context) error

Load resets manager state from the backing store.

func (*Manager) LookupSessionAffinity

func (m *Manager) LookupSessionAffinity(provider, model, sessionID string) (*Auth, string)

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

func (m *Manager) MarkResult(ctx context.Context, result Result)

MarkResult records an execution result and notifies hooks.

func (*Manager) MaxRetryCredentials added in v8.0.70

func (m *Manager) MaxRetryCredentials() int

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

func (m *Manager) NextExecutionSeq() uint64

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

func (m *Manager) PersistCooldownStates(ctx context.Context)

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

func (m *Manager) PluginSchedulerWantsAcrossPriorities() bool

PluginSchedulerWantsAcrossPriorities reports whether the configured plugin scheduler opted into receiving candidates across all priority tiers.

func (*Manager) PrepareHttpRequest

func (m *Manager) PrepareHttpRequest(ctx context.Context, auth *Auth, req *http.Request) error

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

func (m *Manager) ReconcileRegistryModelStates(ctx context.Context, authID string)

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

func (m *Manager) RefreshSchedulerEntry(authID string)

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) Register

func (m *Manager) Register(ctx context.Context, auth *Auth) (*Auth, error)

Register inserts a new auth entry into the manager.

func (*Manager) RegisterExecutor

func (m *Manager) RegisterExecutor(executor ProviderExecutor)

RegisterExecutor registers a provider executor with the manager.

func (*Manager) RegisterExecutorWithRevision added in v8.0.73

func (m *Manager) RegisterExecutorWithRevision(executor ProviderExecutor) uint64

RegisterExecutorWithRevision registers a provider executor and returns the provider's executor revision captured under the same lock as publication, so callers can correlate the revision with this exact registration.

func (*Manager) Remove

func (m *Manager) Remove(ctx context.Context, id string)

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

func (m *Manager) RemoveIf(ctx context.Context, id string, predicate func(*Auth) bool) bool

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

func (m *Manager) ResetQuota(ctx context.Context, authID string) (*Auth, []string, error)

ResetQuota clears quota/cooldown state for an auth and resumes registry routing.

func (*Manager) ResolveExecutionModel

func (m *Manager) ResolveExecutionModel(auth *Auth, routeModel string) string

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

func (m *Manager) RestoreCooldownStates(ctx context.Context) error

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) Selector

func (m *Manager) Selector() Selector

Selector returns the current credential selector.

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 (m *Manager) SetSelector(selector Selector)

func (*Manager) SetStore

func (m *Manager) SetStore(store Store)

SetStore swaps the underlying persistence store.

func (*Manager) StartAutoRefresh

func (m *Manager) StartAutoRefresh(parent context.Context, interval time.Duration)

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

func (m *Manager) SupportsApplyPatchForProviders(providers []string) bool

SupportsApplyPatchForProviders requires support from every routing candidate.

func (*Manager) SupportsNativeToolSearchForModel added in v8.0.24

func (m *Manager) SupportsNativeToolSearchForModel(model string) bool

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

func (m *Manager) UnregisterExecutor(provider string)

UnregisterExecutor removes the executor associated with the provider key.

func (*Manager) Update

func (m *Manager) Update(ctx context.Context, auth *Auth) (*Auth, error)

Update replaces an existing auth entry and notifies hooks.

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

func (m *Manager) UpdatePreparedAuth(ctx context.Context, base, updated *Auth) (*Auth, error)

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

func (m *Manager) UpdateRefreshedAuth(ctx context.Context, base, updated *Auth) (*Auth, error)

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

func (m *Manager) VerifyInference(ctx context.Context, id, model string) (*Auth, error)

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

func (m *Manager) WatchAuthChanges(authID string) (<-chan struct{}, func())

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 mirrors whether the model is temporarily blocked for retries.
	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

func (NoopHook) OnAuthRegistered(context.Context, *Auth)

OnAuthRegistered implements Hook.

func (NoopHook) OnAuthUpdated

func (NoopHook) OnAuthUpdated(context.Context, *Auth)

OnAuthUpdated implements Hook.

func (NoopHook) OnResult

func (NoopHook) OnResult(context.Context, Result)

OnResult 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

type PostAuthHook func(context.Context, *Auth) error

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

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 RecentRequestBucket struct {
	Time    string `json:"time"`
	Success int64  `json:"success"`
	Failed  int64  `json:"failed"`
}

type RefreshEvaluator

type RefreshEvaluator interface {
	ShouldRefresh(now time.Time, auth *Auth) bool
}

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

type RequestInfo struct {
	Query   url.Values
	Headers http.Header
}

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

type RequestPreparer interface {
	PrepareRequest(req *http.Request, auth *Auth) error
}

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

type ResultPolicy interface {
	ApplyResultPolicy(ctx context.Context, result Result) Result
}

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

type ResultPolicyFunc func(ctx context.Context, result Result) Result

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.

func (*RoundRobinSelector) Pick

func (s *RoundRobinSelector) Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, auths []*Auth) (*Auth, error)

Pick selects the next available auth for the provider in a round-robin manner.

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

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.

func (*WeightedRoundRobinSelector) Pick

func (s *WeightedRoundRobinSelector) Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, auths []*Auth) (*Auth, error)

Pick selects the next available auth using smooth weighted round-robin.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL