auth

package
v7.3.4 Latest Latest
Warning

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

Go to latest
Published: Sep 15, 2026 License: MIT Imports: 55 Imported by: 4

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"
	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 (
	AttributeAuthIndexSeed = "auth_index_seed"
	AttributePluginVirtual = "plugin_virtual"
	AttributeVirtualSource = "virtual_source"
)
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 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 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 added in v7.2.116

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 ApplyAuthWeightMetadata added in v7.2.104

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 CanonicalCredentialMetadataKey added in v7.2.140

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 added in v7.2.147

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 added in v7.2.158

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

ClearUnauthorizedModelStates resets model states whose last error was an unauthorized failure.

func CodexAPIKeyModelIsCompat added in v7.2.121

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 and codex.optimize-multi-agent-v2 is also true, Codex MultiAgentV2 agent_message items are converted into portable Responses message/user input for third-party Responses-compatible endpoints.

func CredentialsChanged added in v7.2.158

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 added in v7.2.147

func ExtractUpstreamErrorSummary(raw string) string

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

func HasAuthCreationIntent added in v7.2.158

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 HasKnownAntigravityCreditsHint

func HasKnownAntigravityCreditsHint(authID string) bool

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

func IsAuthTokenPayloadKey added in v7.2.132

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 IsConfigAPIKeyAuth added in v7.2.5

func IsConfigAPIKeyAuth(auth *Auth) bool

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

func IsPluginVirtualAuth added in v7.2.23

func IsPluginVirtualAuth(auth *Auth) bool

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

func IsTerminalAuthError added in v7.2.156

func IsTerminalAuthError(err error) bool

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

func MarkPluginVirtualAuth added in v7.2.23

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

MarkPluginVirtualAuth marks an auth that was expanded from a plugin-owned source file.

func MergeExistingAuthMetadata added in v7.2.132

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 added in v7.2.96

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

NewHomeConcurrencyBusyError creates a typed Home concurrency busy error.

func NewModelCooldownError added in v7.2.147

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

NewModelCooldownError creates an error representing model-level cooldown.

func NewTerminalAuthError added in v7.2.156

func NewTerminalAuthError(err *Error, cause error) error

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

func NormalizeCredentialMetadata added in v7.2.140

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 added in v7.2.116

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 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 added in v7.2.22

func OAuthModelAliasesFromAttributes(attributes map[string]string) []internalconfig.OAuthModelAlias

OAuthModelAliasesFromAttributes returns sanitized per-auth OAuth model aliases from auth attributes.

func ProviderRefreshLead

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

func ProviderSupportsQuotaObservation added in v7.2.142

func ProviderSupportsQuotaObservation(provider string) bool

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

func QuotaCooldownDisabledForAuth added in v7.2.148

func QuotaCooldownDisabledForAuth(auth *Auth) bool

QuotaCooldownDisabledForAuth returns whether cooling is disabled for the auth under global settings.

func QuotaCooldownDisabledForAuthWithConfig added in v7.2.148

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 ResolvedAPIKeyModelInfo added in v7.2.105

func ResolvedAPIKeyModelInfo(req cliproxyexecutor.Request) (*registry.ModelInfo, bool)

ResolvedAPIKeyModelInfo returns the exact configured model definition bound to this API-key execution attempt.

func ResolvedModelInfo added in v7.2.148

func ResolvedModelInfo(req cliproxyexecutor.Request) (*registry.ModelInfo, bool)

ResolvedModelInfo returns the authoritative model capabilities bound to this execution attempt.

func SafeResponseHeaders added in v7.2.96

func SafeResponseHeaders(err error) http.Header

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

func SanitizeUpstreamErrorSummary added in v7.2.147

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 added in v7.2.22

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 added in v7.2.19

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 added in v7.2.104

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 added in v7.2.158

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 added in v7.2.147

func WithCause(err *Error, cause error) error

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

func WithDeferredAPIKeyModelAliasRebuild added in v7.2.28

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 WithRequestInfo

func WithRequestInfo(ctx context.Context, info *RequestInfo) context.Context

WithRequestInfo returns a new context with the given RequestInfo attached.

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.

Types

type APIKeyConfigEntry

type APIKeyConfigEntry interface {
	GetAPIKey() string
	GetBaseURL() string
	GetPrefix() string
	GetProxyURL() string
}

APIKeyConfigEntry is a generic interface for API key configurations.

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 added in v7.2.0

func GetAntigravityCreditsHintRequired(ctx context.Context, authID string) (AntigravityCreditsHint, bool, error)

GetAntigravityCreditsHintRequired returns the latest known AI credits state for request-time paths.

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"`
	// 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:"-"`
	// 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"`
	// 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"`
	// 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:"-"`

	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 added in v7.2.150

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 added in v7.2.150

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 added in v7.2.148

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

func (a *Auth) AccountInfo() (string, string)

func (*Auth) AuthKind added in v7.2.33

func (a *Auth) AuthKind() string

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

func (*Auth) AuthSourceKind added in v7.2.33

func (a *Auth) AuthSourceKind() string

AuthSourceKind returns where the Auth entry came from at runtime.

func (*Auth) Clone

func (a *Auth) Clone() *Auth

Clone shallow copies the Auth structure, duplicating maps to avoid accidental mutation.

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 credential expiration timestamp from metadata. It inspects common absolute expiry keys, expires_in plus timestamp, and nested token objects to remain compatible with legacy auth file formats. If the access_token contains a valid JWT exp claim, it is given priority.

func (*Auth) HasValidAccessToken added in v7.2.148

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

func (a *Auth) ProxyInfo() string

func (*Auth) RecentRequestsSnapshot

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

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) 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 CooldownStateRecord added in v7.2.19

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"`
}

CooldownStateRecord is a persisted runtime cooldown snapshot for one auth/model pair.

type CooldownStateStore added in v7.2.19

type CooldownStateStore interface {
	Load(context.Context) ([]CooldownStateRecord, error)
	Save(context.Context, []CooldownStateRecord) error
}

CooldownStateStore persists runtime cooldown state independently from auth tokens.

type CooldownStateStoreProvider added in v7.2.102

type CooldownStateStoreProvider interface {
	CooldownStateStore() CooldownStateStore
}

CooldownStateStoreProvider exposes a backend-specific cooldown state store.

type CooldownView added in v7.3.0

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 added in v7.3.0

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"`
}

Error describes an authentication related failure in a provider agnostic format.

func NewRequestScopedError added in v7.2.133

func NewRequestScopedError(message string, httpStatus int) *Error

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

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) IsRequestScoped added in v7.2.80

func (e *Error) IsRequestScoped() bool

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

func (*Error) MarkRequestScoped added in v7.2.133

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 FileCooldownStateStore added in v7.2.19

type FileCooldownStateStore struct {
	// contains filtered or unexported fields
}

FileCooldownStateStore stores cooldown state as one .cds file per auth.

func NewFileCooldownStateStore added in v7.2.19

func NewFileCooldownStateStore(dir string) *FileCooldownStateStore

NewFileCooldownStateStore creates a file-backed cooldown state store rooted at dir.

func NewFileCooldownStateStoreWithAuthDir added in v7.2.19

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 added in v7.2.19

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

func (*FileCooldownStateStore) Save added in v7.2.19

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 added in v7.2.156

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 added in v7.2.96

type HomeConcurrencyBusyError struct {
	// contains filtered or unexported fields
}

HomeConcurrencyBusyError is a trusted, Home-originated concurrency admission failure.

func (*HomeConcurrencyBusyError) Error added in v7.2.96

func (e *HomeConcurrencyBusyError) Error() string

func (*HomeConcurrencyBusyError) RetryAfter added in v7.2.96

func (e *HomeConcurrencyBusyError) RetryAfter() *time.Duration

func (*HomeConcurrencyBusyError) SafeResponseHeaders added in v7.2.96

func (e *HomeConcurrencyBusyError) SafeResponseHeaders() http.Header

func (*HomeConcurrencyBusyError) StatusCode added in v7.2.96

func (e *HomeConcurrencyBusyError) StatusCode() int

func (*HomeConcurrencyBusyError) Unwrap added in v7.2.96

func (e *HomeConcurrencyBusyError) Unwrap() error

Unwrap preserves the Home error's code, retryability, and status for errors.As callers.

type HomeDispatchBundle added in v7.2.96

type HomeDispatchBundle struct {
	// contains filtered or unexported fields
}

HomeDispatchBundle is the immutable client and registry pair for one Home lifetime.

type HomeDispatchSelection added in v7.2.96

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 added in v7.2.96

func (s *HomeDispatchSelection) Active() bool

Active reports whether the selection has not ended.

func (*HomeDispatchSelection) AttemptContext added in v7.2.96

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 added in v7.2.96

func (s *HomeDispatchSelection) Bind(closeFn func() error) error

Bind adds a resource to be closed when this selection ends or drains.

func (*HomeDispatchSelection) CloneAuth added in v7.2.96

func (s *HomeDispatchSelection) CloneAuth() *Auth

CloneAuth returns a standalone auth copy without the selection handle.

func (*HomeDispatchSelection) CloneAuthForRoute added in v7.2.96

func (s *HomeDispatchSelection) CloneAuthForRoute(routeModel string) *Auth

CloneAuthForRoute returns an auth copy adapted for a retained canonical route.

func (*HomeDispatchSelection) End added in v7.2.96

func (s *HomeDispatchSelection) End(reason string)

End closes all bound resources and releases the Home execution scope once.

func (*HomeDispatchSelection) EndWithRelease added in v7.2.96

func (s *HomeDispatchSelection) EndWithRelease(reason string) *executionregistry.ReleaseTicket

EndWithRelease closes all bound resources and returns the Home release ticket.

func (*HomeDispatchSelection) ReplaceAuth added in v7.2.111

func (s *HomeDispatchSelection) ReplaceAuth(auth *Auth)

ReplaceAuth updates the selection after Home returns refreshed credentials.

func (*HomeDispatchSelection) Retain added in v7.2.96

func (s *HomeDispatchSelection) Retain()

Retain transfers selection ownership from a request to an execution session.

func (*HomeDispatchSelection) Retained added in v7.2.96

func (s *HomeDispatchSelection) Retained() bool

Retained reports whether an executor transferred this selection to a session.

type HomeInFlightPublisherConfig added in v7.2.96

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 added in v7.2.96

func HomeInFlightPublisherConfigFromConfig(cfg internalconfig.CredentialInFlightConfig) (HomeInFlightPublisherConfig, error)

HomeInFlightPublisherConfigFromConfig converts validated runtime config into publisher bounds.

type HomeInFlightTransport added in v7.2.96

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 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 added in v7.2.96

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 added in v7.2.96

func (m *Manager) ApplyHomeInFlightPublisherConfig(cfg HomeInFlightPublisherConfig)

ApplyHomeInFlightPublisherConfig stores an immutable validated publisher config snapshot.

func (*Manager) AvailableProviders added in v7.2.8

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) ClearHomeDispatchBundle added in v7.2.96

func (m *Manager) ClearHomeDispatchBundle(bundle *HomeDispatchBundle) bool

ClearHomeDispatchBundle removes bundle only when it still belongs to the active lifetime.

func (*Manager) ClearHomeExecutionRegistry added in v7.2.96

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

Execute performs a non-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) ExecuteCount

It supports multiple providers for the same model and round-robins the starting provider per model.

func (*Manager) ExecuteStream

ExecuteStream performs a streaming execution using the configured selector and executor. It supports multiple providers for the same model and round-robins the starting provider per model.

func (*Manager) Executor

func (m *Manager) Executor(provider string) (ProviderExecutor, bool)

Executor returns the registered provider executor for a provider key.

func (*Manager) ForceRefreshAll added in v7.2.156

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 added in v7.2.156

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 added in v7.0.1

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

GetExecutionSessionAuthByID retrieves a Home runtime auth scoped to an execution session.

func (*Manager) HasProviderAuth added in v7.2.8

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 added in v7.2.96

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 added in v7.2.96

func (m *Manager) HomeExecutionRegistry() *executionregistry.Registry

HomeExecutionRegistry returns the registry from the active Home lifetime bundle.

func (*Manager) HomeInFlightPublisherConfig added in v7.2.96

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) 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 added in v7.2.156

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) 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) PersistCooldownStates added in v7.2.96

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

PersistCooldownStates writes the current cooldown snapshot using ctx.

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 added in v7.3.4

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 added in v7.2.96

func (m *Manager) PublishHomeDispatch(client homeAuthDispatcher, registry *executionregistry.Registry, generation uint64) *HomeDispatchBundle

PublishHomeDispatch publishes the selectable Home lifetime as one atomic bundle.

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 added in v7.2.28

func (m *Manager) RefreshAPIKeyModelAlias()

RefreshAPIKeyModelAlias rebuilds the API-key model alias table from the current runtime config.

func (*Manager) RefreshHomeSelectionAfterUnauthorized added in v7.2.116

func (m *Manager) RefreshHomeSelectionAfterUnauthorized(_ 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 added in v7.1.47

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) Remove added in v7.1.43

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) ReportHomeUnauthorized added in v7.2.116

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 added in v7.2.22

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 added in v7.2.124

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 added in v7.2.19

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

RestoreCooldownStates restores unexpired persisted cooldown records into registered auths.

func (*Manager) ResultPolicy added in v7.2.158

func (m *Manager) ResultPolicy() ResultPolicy

ResultPolicy returns the current execution result policy, or nil if none is configured.

func (*Manager) SelectAuth added in v7.2.70

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 added in v7.2.74

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) SelectAuthWithCredentialPolicy added in v7.2.113

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 added in v7.2.96

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 added in v7.2.113

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 added in v7.2.96

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 added in v7.2.96

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 added in v7.2.19

func (m *Manager) SetCooldownStateStore(store CooldownStateStore)

SetCooldownStateStore swaps the independent runtime cooldown state store.

func (*Manager) SetHomeExecutionRegistry added in v7.2.96

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 added in v7.1.57

func (m *Manager) SetPluginScheduler(scheduler PluginScheduler)

func (*Manager) SetResultPolicy added in v7.2.158

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 added in v7.2.96

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) SwapCooldownStateStore added in v7.2.96

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) UpdatePreparedAuth added in v7.2.150

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 added in v7.2.150

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

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"`
}

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 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 added in v7.2.34

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 added in v7.1.57

type PluginScheduler interface {
	PickAuth(context.Context, pluginapi.SchedulerPickRequest) (pluginapi.SchedulerPickResponse, bool, error)
}

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 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"`
}

QuotaState contains limiter tracking data for a credential.

func (*QuotaState) ClearObservationSignals added in v7.2.142

func (q *QuotaState) ClearObservationSignals() bool

ClearObservationSignals removes only passive observation data. It leaves cooldown and scheduler state untouched.

func (QuotaState) Clone added in v7.2.142

func (q QuotaState) Clone() QuotaState

Clone returns an independent copy of the quota state.

func (*QuotaState) ObserveResponseHeadersForProvider added in v7.2.142

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 added in v7.1.19

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
	// 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
}

Result captures execution outcome used to adjust auth state.

type ResultPolicy added in v7.2.158

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 added in v7.2.158

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

ResultPolicyFunc enables using a plain function as a ResultPolicy.

func (ResultPolicyFunc) ApplyResultPolicy added in v7.2.158

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 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
}

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) 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 added in v7.2.156

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 added in v7.2.133

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) (*Auth, 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 added in v7.2.147

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 added in v7.2.147

func NewSessionCacheWithCapacity(ttl time.Duration, maxEntries int) *SessionCache

NewSessionCacheWithCapacity creates a cache with the specified TTL and max entries limit.

func (*SessionCache) CompareAndDelete added in v7.2.133

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 added in v7.2.147

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 added in v7.2.103

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 added in v7.2.133

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.
	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 added in v7.2.34

type StreamRewriteOptions struct {
	RewriteModel string
}

StreamRewriteOptions configures the stream rewriter.

type StreamRewriter added in v7.2.34

type StreamRewriter struct {
	// contains filtered or unexported fields
}

StreamRewriter rewrites model names in streaming SSE responses.

func NewStreamRewriter added in v7.2.34

func NewStreamRewriter(options StreamRewriteOptions) *StreamRewriter

NewStreamRewriter creates a new stream rewriter.

func (*StreamRewriter) Finish added in v7.2.34

func (r *StreamRewriter) Finish() []byte

Finish flushes any buffered partial SSE data at the end of a stream.

func (*StreamRewriter) RewriteChunk added in v7.2.34

func (r *StreamRewriter) RewriteChunk(chunk []byte) []byte

RewriteChunk rewrites model names in a single SSE chunk.

type WeightedRoundRobinSelector added in v7.2.104

type WeightedRoundRobinSelector struct {
	// contains filtered or unexported fields
}

WeightedRoundRobinSelector provides smooth weighted round-robin selection.

func (*WeightedRoundRobinSelector) Pick added in v7.2.104

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