auth

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 44 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// CredentialPolicyMetadataKey stores the dispatch credential policy in Options.Metadata.
	CredentialPolicyMetadataKey = "credential_policy"
	// CredentialPolicyCodexAlphaSearchV1 selects credentials supported by Codex Alpha Search.
	CredentialPolicyCodexAlphaSearchV1 = "codex_alpha_search_v1"

	// AttributeCodexAlphaSearch marks an opted-in Codex API key.
	AttributeCodexAlphaSearch = "codex_alpha_search"

	AuthKindAPIKey = "apikey"
	AuthKindOAuth  = "oauth"
)
View Source
const AllowedAuthIDsMetadataKey = "allowed_auth_ids"

AllowedAuthIDsMetadataKey stores the dispatch allowlist in Options.Metadata.

View Source
const AllowedModelIDsMetadataKey = "allowed_model_ids"

AllowedModelIDsMetadataKey stores the model allowlist in Options.Metadata.

View Source
const ErrorCodeForceCooldown = "force_cooldown"

ErrorCodeForceCooldown marks failures that must enforce credential cooldown even when cooling is disabled or the HTTP status is not normally cooled.

View Source
const ErrorCodeRefreshOutcomeUnknown = "refresh_outcome_unknown"

ErrorCodeRefreshOutcomeUnknown identifies legacy refresh diagnostics. New failures use the normal transient refresh error and bounded backoff.

View Source
const ErrorCodeRequestScoped = "request_scoped"

ErrorCodeRequestScoped marks failures belonging to one downstream request. They must not change credential or model availability.

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 because of it.

View Source
const ExcludedAuthIDsMetadataKey = "excluded_auth_ids"

ExcludedAuthIDsMetadataKey stores credential IDs already attempted for the current request retry round in Options.Metadata.

View Source
const ExcludedConcurrencyCandidatesMetadataKey = "excluded_concurrency_candidates"

ExcludedConcurrencyCandidatesMetadataKey stores candidates rejected by atomic concurrency admission during this dispatch attempt.

View Source
const PinnedAuthIDMetadataKey = "pinned_auth_id"

PinnedAuthIDMetadataKey stores an explicit pinned credential ID in Options.Metadata.

View Source
const PinnedAuthMetadataKey = PinnedAuthIDMetadataKey

PinnedAuthMetadataKey aliases PinnedAuthIDMetadataKey for CPA metadata parity.

View Source
const RequestRetryRoundMetadataKey = "request_retry_round"

RequestRetryRoundMetadataKey stores the zero-based request retry round in Options.Metadata. Round zero is the initial credential round.

View Source
const RequestedModelMetadataKey = "requested_model"

RequestedModelMetadataKey stores the client-requested model name in Options.Metadata. It is used to preserve the original model string across prefix rewriting / alias resolution.

Variables

View Source
var (
	ErrFullAuthNotFound   = errors.New("full auth not found")
	ErrRefreshUnsupported = &Error{
		Code:       refreshUnsupportedCode,
		Message:    refreshUnsupportedMsg,
		HTTPStatus: http.StatusServiceUnavailable,
	}
)
View Source
var ErrAuthNotFound = errors.New("auth: credential not found")

ErrAuthNotFound reports an authoritative credential lookup or mutation whose target no longer exists. It is distinct from an unloaded local credential.

View Source
var ErrAuthNotLoaded = errors.New("auth manager: credential is not loaded")

ErrAuthNotLoaded reports a result for a credential this manager has not loaded. Callers that can resolve the authoritative credential should load it and retry instead of dropping the result.

View Source
var ErrCooldownMutationUnsupported = errors.New("auth manager: cooldown reset requires an atomic state store")

ErrCooldownMutationUnsupported indicates that the auth store cannot apply an atomic cooldown reset. Home requires atomic mutation so multiple instances sharing one database cannot overwrite each other's credential state.

View Source
var ErrRuntimeProjectionPersist = errors.New("auth: cannot persist an incomplete runtime projection")

ErrRuntimeProjectionPersist prevents scheduling projections from replacing complete credentials in any full-record persistence path.

View Source
var ErrSessionAffinityConflict = errors.New("session affinity binding changed")

ErrSessionAffinityConflict asks dispatch to re-read a concurrently changed binding.

Functions

func AccessTokenSHA256 added in v1.0.65

func AccessTokenSHA256(auth *Auth) string

AccessTokenSHA256 fingerprints an OAuth token without exposing it.

func ApplyCustomHeadersFromMetadata

func ApplyCustomHeadersFromMetadata(auth *Auth)

ApplyCustomHeadersFromMetadata updates apply custom headers from metadata.

func ApplyRefreshPendingState added in v1.0.65

func ApplyRefreshPendingState(auth *Auth, now time.Time)

ApplyRefreshPendingState opens refresh-only backoff without changing request availability.

func ApplyRefreshSuccessState added in v1.0.65

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

ApplyRefreshSuccessState clears refresh errors and unauthorized execution state.

func ApplyUnsupportedRefreshBackoff added in v1.0.65

func ApplyUnsupportedRefreshBackoff(auth *Auth, now time.Time)

ApplyUnsupportedRefreshBackoff clears credential-level refresh blocking while backing off further refresh attempts for an unsupported credential.

func AuthIsNewerThanObserved added in v1.0.65

func AuthIsNewerThanObserved(auth *Auth, observedAccessTokenSHA256 string) bool

AuthIsNewerThanObserved reports whether Home stores a different access token from the one used by the failed downstream attempt.

func CanUseObservedTokenAfterRefreshFailure added in v1.0.72

func CanUseObservedTokenAfterRefreshFailure(auth *Auth, observedAccessTokenSHA256 string, errRefresh error, now time.Time) bool

CanUseObservedTokenAfterRefreshFailure reports whether a downstream caller can safely keep using the exact Antigravity token it observed when refresh fails. This compatibility path never accepts terminal or canceled refreshes.

func CanonicalModelID added in v1.0.62

func CanonicalModelID(model string) string

CanonicalModelID removes a request-option suffix and surrounding whitespace from a model ID.

func ExtractCustomHeadersFromMetadata

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

ExtractCustomHeadersFromMetadata extracts a custom headers from metadata.

func ModelAliasHint added in v1.1.8

func ModelAliasHint(requestedModel string, aliases []string) string

ModelAliasHint formats the public model IDs for a lookup error message.

func NewTransientRefreshError added in v1.0.65

func NewTransientRefreshError() error

NewTransientRefreshError returns a generic refresh acquisition error.

func NormalizeCredentialPolicy added in v1.0.67

func NormalizeCredentialPolicy(policy string) (string, bool)

NormalizeCredentialPolicy validates and canonicalizes a dispatch credential policy.

func NormalizeExplicitID added in v1.0.73

func NormalizeExplicitID(raw string) string

NormalizeExplicitID validates and cleans an explicit session identifier. It trims whitespace, rejects control characters, and rejects IDs exceeding 256 bytes.

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

Supported channels: vertex, antigravity, claude, codex, kimi, xai, meta, devin.

func ProviderRefreshLead

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

ProviderRefreshLead handles a provider refresh lead.

func RefreshBlocksDispatch added in v1.0.72

func RefreshBlocksDispatch(auth *Auth) bool

RefreshBlocksDispatch reports whether a credential-level refresh failure must prevent request selection. Unsupported refresh remains refresh-only backoff and must not be promoted to a dispatch block.

func RefreshRetryBackoffOpen added in v1.0.67

func RefreshRetryBackoffOpen(auth *Auth, now time.Time) bool

RefreshRetryBackoffOpen reports whether provider refresh calls are currently backed off. This state is intentionally ignored by request selection.

func RegisterRefreshLeadProvider

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

RegisterRefreshLeadProvider handles a register refresh lead provider.

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 Auth

type Auth struct {
	// ID uniquely identifies the auth record across restarts.
	ID string `json:"id"`
	// Index is a stable runtime identifier derived from auth metadata (not persisted).
	Index string `json:"-"`
	// Provider is the upstream provider key (e.g. "gemini", "claude").
	Provider string `json:"provider"`
	// Prefix optionally namespaces models for routing (e.g., "teamA/gemini-3-pro-preview").
	Prefix string `json:"prefix,omitempty"`
	// FileName stores the relative or absolute path of the backing auth file.
	FileName string `json:"-"`
	// Storage holds the token persistence implementation used during login flows.
	Storage baseauth.TokenStorage `json:"-"`
	// Label is an optional human readable label for logging.
	Label string `json:"label,omitempty"`
	// Status is the lifecycle status managed by the AuthManager.
	Status Status `json:"status"`
	// StatusMessage holds a short description for the current status.
	StatusMessage string `json:"status_message,omitempty"`
	// Disabled indicates the auth is intentionally disabled by operator.
	Disabled bool `json:"disabled"`
	// Unavailable 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 is carried to CPA; Home does not create upstream pools.
	ProxyConnectionPool *cpaauth.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"`
	// RuntimeProjection marks an incomplete scheduling view that must never be
	// saved as a complete credential. Full database snapshots leave this false.
	RuntimeProjection bool `json:"-"`
	// RuntimeDisableCooling carries the auth-scoped cooling override in minimal
	// projections without serializing provider metadata or secrets.
	RuntimeDisableCooling *bool `json:"-"`
	// RuntimeRefreshBlocked preserves a credential-level refresh block in
	// minimal projections without copying provider response diagnostics.
	RuntimeRefreshBlocked bool `json:"-"`
	// Quota captures recent quota information for load balancers.
	Quota QuotaState `json:"quota"`
	// LastError stores the last failure encountered while executing or refreshing.
	LastError *Error `json:"last_error,omitempty"`
	// LastRefreshError preserves refresh acquisition diagnostics independently
	// from ordinary execution results while refresh backoff remains active.
	LastRefreshError *Error `json:"last_refresh_error,omitempty"`
	// CreatedAt is the creation timestamp in UTC.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is the last modification timestamp in UTC.
	UpdatedAt time.Time `json:"updated_at"`
	// LastRefreshedAt records the last successful refresh time in UTC.
	LastRefreshedAt time.Time `json:"last_refreshed_at"`
	// NextRefreshAfter is the earliest time a refresh should retrigger.
	NextRefreshAfter time.Time `json:"next_refresh_after"`
	// NextRetryAfter is the earliest time a retry should retrigger.
	NextRetryAfter time.Time `json:"next_retry_after"`
	// ModelStates tracks per-model runtime availability data.
	ModelStates map[string]*ModelState `json:"model_states,omitempty"`

	// Runtime carries non-serialisable data used during execution (in-memory only).
	Runtime any `json:"-"`
	// StateVersion is the storage revision of this runtime snapshot when available.
	StateVersion int64 `json:"-"`

	Success int64 `json:"-"`
	Failed  int64 `json:"-"`
	// contains filtered or unexported fields
}

Auth encapsulates the runtime state and metadata associated with a single credential.

func (*Auth) AccountInfo

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

AccountInfo handles an account info.

func (*Auth) AuthKind added in v1.0.67

func (a *Auth) AuthKind() string

AuthKind returns the explicit credential kind or infers it from the credential shape.

func (*Auth) Clone

func (a *Auth) Clone() *Auth

Clone copies the Auth structure, duplicating mutable fields to avoid accidental mutation.

func (*Auth) DisableCoolingOverride

func (a *Auth) DisableCoolingOverride() *bool

DisableCoolingOverride returns the auth-scoped disable_cooling override when present. Runtime projections take precedence over metadata. Metadata is read from "disable_cooling" (or legacy "disable-cooling"). Callers must treat the returned pointer as read-only.

func (*Auth) EnsureIndex

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.

func (*Auth) ProxyInfo

func (a *Auth) ProxyInfo() string

ProxyInfo handles a proxy info.

func (*Auth) RecentRequestsSnapshot

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

RecentRequestsSnapshot handles a recent requests snapshot.

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 CooldownClearResult added in v1.0.67

type CooldownClearResult struct {
	CredentialID  string
	Model         string
	Cleared       bool
	ClearedModels []string
}

CooldownClearResult describes quota cooldown state removed by an operator.

type DispatchDecision

type DispatchDecision struct {
	Auth          *Auth
	Provider      string
	UpstreamModel string
	RequestRetry  int
	PooledModels  bool
	ForceMapping  bool
	OriginalAlias string
}

DispatchDecision captures the scheduler selection for an incoming request.

type Error

type Error struct {
	// Code is a short machine readable identifier.
	Code string `json:"code,omitempty"`
	// Message is a human readable description of the failure.
	Message string `json:"message"`
	// Diagnostic is a redacted internal summary for trusted transports and logs.
	Diagnostic string `json:"diagnostic,omitempty"`
	// Retryable indicates whether a retry might fix the issue automatically.
	Retryable bool `json:"retryable"`
	// HTTPStatus optionally records an HTTP-like status code for the error.
	HTTPStatus int `json:"http_status,omitempty"`
	// Upstream preserves the provider response independently from internal
	// scheduling classification.
	Upstream *UpstreamResponse `json:"upstream,omitempty"`
}

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

func ApplyRefreshFailureState added in v1.0.72

func ApplyRefreshFailureState(auth *Auth, errRefresh error, now time.Time) *Error

ApplyRefreshFailureState backs off credential acquisition after a transient refresh failure. A known-valid Antigravity access token remains dispatchable outside the request safety window while Home retries the refresh.

func (*Error) Error

func (e *Error) Error() string

Error returns the error message.

func (*Error) Is added in v1.0.72

func (e *Error) Is(target error) bool

Is preserves sentinel matching for structured unsupported-refresh errors.

func (*Error) StatusCode

func (e *Error) StatusCode() int

StatusCode returns the HTTP status code.

type ExcludedConcurrencyCandidate added in v1.0.61

type ExcludedConcurrencyCandidate struct {
	CredentialID string
	Model        string
}

ExcludedConcurrencyCandidate identifies a credential-wide or model-scoped exclusion.

type FileTokenStore

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

FileTokenStore persists token records and auth metadata using the filesystem as backing storage.

func NewFileTokenStore

func NewFileTokenStore() *FileTokenStore

NewFileTokenStore creates a token store that saves credentials to disk through the TokenStorage implementation embedded in the token record.

func (*FileTokenStore) Delete

func (s *FileTokenStore) Delete(ctx context.Context, id string) error

Delete removes the auth file.

func (*FileTokenStore) List

func (s *FileTokenStore) List(ctx context.Context) ([]*Auth, error)

List enumerates all auth JSON files under the configured directory.

func (*FileTokenStore) Save

func (s *FileTokenStore) Save(ctx context.Context, auth *Auth) (string, error)

Save persists token storage and metadata to the resolved auth file path.

func (*FileTokenStore) SetBaseDir

func (s *FileTokenStore) SetBaseDir(dir string)

SetBaseDir updates the default directory used for auth JSON persistence when no explicit path is provided.

type FillFirstSelector

type FillFirstSelector struct{}

FillFirstSelector selects the first available credential (deterministic ordering). This "burns" one account before moving to the next, which can help stagger rolling-window subscription caps (e.g. chat message limits).

func (*FillFirstSelector) Pick

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

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

type FullAuthResolver added in v1.0.2

type FullAuthResolver interface {
	GetFullAuth(ctx context.Context, uuid string) (*Auth, error)
}

type Manager

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

Manager orchestrates auth lifecycle, selection, and persistence for CLIProxyAPIHome.

This is intentionally narrower than CPA's full execution manager: it only supports registering/updating auths, scheduling selection (Dispatch), and background refresh.

func NewManager

func NewManager(store Store, selector Selector, _ any) *Manager

NewManager creates a new manager.

func (*Manager) AccountReusedSelection added in v1.1.10

func (m *Manager) AccountReusedSelection(ctx context.Context, providers []string, model, authIndex, eventID string, opts Options)

AccountReusedSelection charges an execution that reused a CPA-held selection. It neither selects a credential nor acquires concurrency or changes bindings. The pool uses current Home availability and the same API-key/model/policy restrictions as dispatch, within the retained credential's priority tier.

func (*Manager) AliasesForUpstreamModel added in v1.1.8

func (m *Manager) AliasesForUpstreamModel(requestedModel string, access *ModelAccess) []string

AliasesForUpstreamModel returns only published aliases visible to the caller. Permissions are checked before deduplication and truncation, using each target alias's model-specific channel scope rather than the requested ID's.

func (*Manager) CanAccountReusedSelection added in v1.1.10

func (m *Manager) CanAccountReusedSelection(ctx context.Context, model, authIndex, policy, eventID string) bool

CanAccountReusedSelection reports whether a reused execution can change weighted credits, before the caller queries external API-key permissions.

func (*Manager) ClearDisabledCooldownStates added in v1.0.69

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

ClearDisabledCooldownStates clears request-error and quota cooldown state covered by the global or auth-scoped disable-cooling setting. Cluster-backed stores are mutated through StateMutator so the persisted row remains authoritative across Home nodes.

func (*Manager) ClearQuotaCooldown added in v1.0.67

func (m *Manager) ClearQuotaCooldown(ctx context.Context, credentialID, model string) (CooldownClearResult, error)

ClearQuotaCooldown atomically clears model quota cooldown state for one credential. An empty model clears every model; a non-empty model clears only that canonical model key.

func (*Manager) Delete

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

Delete handles delete.

func (*Manager) DescribeModelStates added in v1.1.1

func (m *Manager) DescribeModelStates(auth *Auth, modelFilter string, now time.Time) []ModelStateView

DescribeModelStates reads one auth snapshot without selecting credentials or changing state. Registered route models resolve through the same prefix and alias pipeline as Dispatch. Unregistered historical keys are opaque state identifiers and are not aliased again.

func (*Manager) Dispatch

func (m *Manager) Dispatch(ctx context.Context, providers []string, requestedModel string, opts Options) (*DispatchDecision, error)

Dispatch processes dispatch.

func (*Manager) FenceDisabledCooldownStates added in v1.0.69

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

FenceDisabledCooldownStates clears covered cooldown state and advances the revision of auths with queued result snapshots or a prior failed cleanup. It is used when global disable-cooling changes so older asynchronous snapshots cannot restore a cooldown after the configuration switch.

func (*Manager) GetByID

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

GetByID returns a by id.

func (*Manager) GetByIndex

func (m *Manager) GetByIndex(index string) (*Auth, bool)

GetByIndex returns a by index.

func (*Manager) List

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

List returns the available entries.

func (*Manager) MarkResult

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

MarkResult records a downstream execution result and updates auth cooldown state.

func (*Manager) ReconcileRegistryModelStates

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

ReconcileRegistryModelStates aligns the derived model registry with the authoritative scheduler state held by this Home instance.

func (*Manager) RefreshAuthCredential added in v1.0.2

func (m *Manager) RefreshAuthCredential(ctx context.Context, target *Auth) (*Auth, error)

RefreshAuthCredential refreshes a full auth value without updating memory or persistence.

func (*Manager) RefreshNow

func (m *Manager) RefreshNow(ctx context.Context, authIndex string) (*Auth, error)

RefreshNow forces a best-effort credential refresh for the given auth. It updates the in-memory record and persists it when enabled.

func (*Manager) RefreshNowObserved added in v1.0.65

func (m *Manager) RefreshNowObserved(ctx context.Context, authIndex, observedAccessTokenSHA256 string) (*Auth, error)

RefreshNowObserved refreshes unless Home already replaced the access token observed by the downstream attempt that received a 401.

func (*Manager) RefreshSchedulerEntry

func (m *Manager) RefreshSchedulerEntry(authID string)

RefreshSchedulerEntry refreshes refresh scheduler entry.

func (*Manager) Register

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

Register wires package handlers into the provided registry.

func (*Manager) ResolveExecutionModel added in v1.1.1

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

ResolveExecutionModel returns the auth-specific upstream model that dispatch would send for a public route model, or the trimmed route model when no alias applies.

func (*Manager) SetAutoRefreshHandler added in v1.0.65

func (m *Manager) SetAutoRefreshHandler(handler func(context.Context, *Auth) error)

SetAutoRefreshHandler routes background refresh through the cluster lock owner.

func (*Manager) SetConfig

func (m *Manager) SetConfig(cfg *internalconfig.Config)

SetConfig sets a config.

func (*Manager) SetFullAuthResolver added in v1.0.2

func (m *Manager) SetFullAuthResolver(resolver FullAuthResolver)

SetFullAuthResolver sets a full auth resolver.

func (*Manager) SetModelAliasHints added in v1.1.8

func (m *Manager) SetModelAliasHints(auth *Auth, publicModels []string)

SetModelAliasHints indexes the effective upstream models behind published public model IDs, including OAuth aliases and credential prefixes. Passing no public models removes this credential's hints.

func (*Manager) SetOAuthModelAlias

func (m *Manager) SetOAuthModelAlias(aliases map[string][]internalconfig.OAuthModelAlias)

SetOAuthModelAlias updates the OAuth model name alias table used during execution. The alias is applied per-auth channel to resolve the upstream model name while keeping the client-visible model name unchanged for translation/response formatting.

func (*Manager) SetPluginAuthRefresher added in v1.0.39

func (m *Manager) SetPluginAuthRefresher(refresher PluginAuthRefresher)

SetPluginAuthRefresher sets the optional plugin auth refresher.

func (*Manager) SetPluginScheduler added in v1.0.39

func (m *Manager) SetPluginScheduler(scheduler PluginScheduler)

SetPluginScheduler sets the optional plugin scheduler.

func (*Manager) SetRoundTripperProvider

func (m *Manager) SetRoundTripperProvider(p RoundTripperProvider)

SetRoundTripperProvider sets a round tripper provider.

func (*Manager) SetSelector

func (m *Manager) SetSelector(selector Selector)

SetSelector sets a selector.

func (*Manager) SetStore added in v1.0.2

func (m *Manager) SetStore(store Store)

SetStore sets a store.

func (*Manager) ShouldRefreshCredential added in v1.0.56

func (m *Manager) ShouldRefreshCredential(auth *Auth, now time.Time) bool

ShouldRefreshCredential reports whether the credential is due for refresh.

func (*Manager) Shutdown added in v1.0.2

func (m *Manager) Shutdown()

Shutdown stops background auth work and releases selector resources.

func (*Manager) StartAutoRefresh

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

StartAutoRefresh starts an auto refresh.

func (*Manager) StopAutoRefresh

func (m *Manager) StopAutoRefresh()

StopAutoRefresh stops an auto refresh.

func (*Manager) Update

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

Update updates the value.

func (*Manager) UsesWeightedRouting added in v1.1.10

func (m *Manager) UsesWeightedRouting() bool

UsesWeightedRouting reports whether built-in weighted routing owns accounting, including an affinity wrapper but excluding an active scheduler plugin.

type ModelAccess added in v1.1.3

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

ModelAccess is a read-only credential/model policy for catalog enumeration. Nil sets are unrestricted; non-nil empty sets deny all access. It deliberately excludes transient scheduling and concurrency state.

func NewModelAccess added in v1.1.3

func NewModelAccess(authIDs, modelIDs []string, modelAuthIDs map[string][]string) *ModelAccess

NewModelAccess normalizes catalog restrictions using the dispatch filters. Model-specific credential sets are intersected with the base credential set.

func (*ModelAccess) Allows added in v1.1.3

func (a *ModelAccess) Allows(authID, modelID string) bool

Allows reports whether a credential may expose this public model ID. A nil policy preserves the unscoped catalog used outside database-backed Home.

type ModelState

type ModelState struct {
	// Status reflects the lifecycle status for this model.
	Status Status `json:"status"`
	// StatusMessage provides an optional short description of the status.
	StatusMessage string `json:"status_message,omitempty"`
	// Unavailable 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"`
	// QuotaResetAt marks an operator reset so peers can merge it without
	// discarding unrelated local execution errors.
	QuotaResetAt time.Time `json:"quota_reset_at,omitzero"`
	// LastObservedAt is the event time of the newest usage result applied to
	// this model. Older or replayed results are fenced by it.
	LastObservedAt time.Time `json:"last_observed_at,omitzero"`
}

ModelState captures the execution state for a specific model under an auth entry.

func MergePersistedModelState added in v1.0.67

func MergePersistedModelState(persistedState, localState *ModelState) *ModelState

MergePersistedModelState combines authoritative persisted quota state with newer execution-only state accumulated by one Home instance.

func (*ModelState) Clone

func (m *ModelState) Clone() *ModelState

Clone duplicates a model state including nested error details.

type ModelStateView added in v1.1.1

type ModelStateView struct {
	Model          string
	UpstreamModel  string
	StateKey       string
	DisplayName    string
	Registered     bool
	State          *ModelState
	Blocked        bool
	BlockReason    string
	NextRetryAfter time.Time
}

ModelStateView pairs recorded execution state with effective scheduling availability. State is diagnostic history; Blocked and NextRetryAfter apply the current cooling policy.

type Options

type Options struct {
	Headers         http.Header
	Query           url.Values
	OriginalRequest []byte
	Metadata        map[string]any
	SessionAffinity *SessionAffinitySelection
	// SessionAffinityScope overrides the binding namespace, not candidate filtering
	// or weighted accounting. Empty uses the provider passed to the selector.
	SessionAffinityScope string
	// ExcludedProviders fences unavailable pools without changing session-binding namespaces.
	ExcludedProviders []string
}

Options carries optional request hints used during dispatch selection.

This is a deliberately small subset of CPA's execution options: CLIProxyAPIHome only needs headers / query / raw request bytes for selector decisions, and a generic metadata bag.

type PluginAuthRefresher added in v1.0.39

type PluginAuthRefresher interface {
	RefreshAuth(context.Context, *Auth) (*Auth, bool, error)
}

PluginAuthRefresher lets provider plugins refresh Home-owned auth records.

type PluginScheduler added in v1.0.39

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

PluginScheduler lets scheduler plugins select from Home-filtered auth candidates.

type PostAuthHook

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 QuotaState

type QuotaState struct {
	// Exceeded indicates the credential recently hit a quota error.
	Exceeded bool `json:"exceeded"`
	// Scope records that this quota is model-scoped or aggregated from models.
	Scope string `json:"scope,omitempty"`
	// Reason provides an optional provider specific human readable description.
	Reason string `json:"reason,omitempty"`
	// NextRecoverAt is when the credential may become available again.
	NextRecoverAt time.Time `json:"next_recover_at"`
	// BackoffLevel stores the progressive cooldown exponent used for rate limits.
	BackoffLevel int `json:"backoff_level,omitempty"`
}

QuotaState contains limiter tracking data for a credential.

type RecentRequestBucket

type 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 Result

type Result struct {
	AuthID            string
	AuthIndex         string
	Provider          string
	Model             string
	Success           bool
	Error             *Error
	RetryAfter        *time.Duration
	ResetAt           *time.Time
	AccessTokenSHA256 string
	// ObservedAt is the event time of the usage result. Non-zero values fence
	// replayed or out-of-order deliveries against the model state.
	ObservedAt time.Time
	// RequestStatsEventID identifies a completed execution independently of usage
	// persistence. Identified replays count only if this manager has not counted it.
	RequestStatsEventID string
	// SkipRequestStats suppresses statistics for legacy replays without an event ID.
	SkipRequestStats bool
}

Result captures an upstream execution result reported by a downstream CPA node.

func NewUsageResult

func NewUsageResult(authIndex, provider, model string, statusCode int, body string) Result

NewUsageResult creates a new usage result.

func NewUsageResultWithCode added in v1.1.8

func NewUsageResultWithCode(authIndex, provider, model string, statusCode int, body string, code string) Result

NewUsageResultWithCode creates a usage result carrying a structured failure classification (e.g. ErrorCodeStreamTruncated) reported by the downstream.

func (Result) RequestScoped added in v1.1.10

func (r Result) RequestScoped() bool

RequestScoped reports failures which must not participate in credential feedback.

type RoundRobinSelector

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

RoundRobinSelector provides a simple provider scoped round-robin selection strategy.

func (*RoundRobinSelector) Pick

func (s *RoundRobinSelector) Pick(ctx context.Context, provider, model string, opts 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 Options, auths []*Auth) (*Auth, error)
}

Selector chooses an auth candidate for dispatch.

type SessionAffinityCommit added in v1.1.6

type SessionAffinityCommit struct {
	Key              string
	ExpectedRevision string
	// ExpiredAt guards a cold selection based on an expired snapshot against
	// a concurrent renewal that keeps the same credential revision.
	ExpiredAt time.Time
	AuthID    string
	TTL       time.Duration
	// SessionKey and Provider record a successful selection for cross-model
	// Guardian inheritance. SessionKey hashes the session without its model or provider.
	// Empty metadata keeps ordinary affinity without recording Guardian history.
	SessionKey string
	Provider   string
}

SessionAffinityCommit conditionally renews or replaces a binding.

type SessionAffinityConfig

type SessionAffinityConfig struct {
	Fallback         Selector
	TTL              time.Duration
	Store            SessionAffinityStore
	SubagentAffinity *bool
	RebindOn         string
}

SessionAffinityConfig configures the session affinity selector.

type SessionAffinitySelection added in v1.1.6

type SessionAffinitySelection struct {
	Store  SessionAffinityStore
	Commit *SessionAffinityCommit
	// contains filtered or unexported fields
}

SessionAffinitySelection defers binding changes until dispatch is prepared and admitted. Each dispatch attempt owns its selection; selectors must not share it.

func (*SessionAffinitySelection) Finish added in v1.1.10

func (s *SessionAffinitySelection) Finish(committed bool)

Finish confirms weighted credit after successful binding/admission, or releases it on failure/retry. Dispatch must finish each selection before discarding it. It is safe to call repeatedly, including with a nil selection.

func (*SessionAffinitySelection) Reset added in v1.1.10

func (s *SessionAffinitySelection) Reset()

Reset releases any pending reservation before clearing selection metadata. It is safe to call repeatedly, including with a nil selection.

type SessionAffinitySelector

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

SessionAffinitySelector wraps another selector with session-sticky behavior. It extracts session ID from multiple sources and maintains session-to-auth mappings with automatic failover when the bound auth becomes unavailable.

func NewSessionAffinitySelectorWithConfig

func NewSessionAffinitySelectorWithConfig(cfg SessionAffinityConfig) *SessionAffinitySelector

NewSessionAffinitySelectorWithConfig creates a selector with custom configuration.

func (*SessionAffinitySelector) InvalidateAuth

func (s *SessionAffinitySelector) InvalidateAuth(authID string)

InvalidateAuth removes local bindings when a credential is removed. Shared bindings are revalidated against each request's candidates and replaced by CAS, so a delayed node-local invalidation cannot delete a newer cluster binding.

func (*SessionAffinitySelector) Pick

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

Pick selects an auth with session affinity when possible. Priority for session ID extraction:

  1. Anthropic / Claude Code headers (X-Claude-Code-Session-Id, X-Claude-Code-Agent-Id)
  2. Claude Code metadata.user_id in payload (user_xxx_account__session_xxx)
  3. OpenAI / Codex CLI headers (Session-Id, Session_id, X-Codex-Parent-Thread-Id)
  4. Antigravity CLI headers (X-Http-Session-Id)
  5. Explicit session headers (X-Session-ID, X-Session-Affinity, X-Slot-Session-Id)
  6. Conversation / Client headers (X-Conversation-Id, X-Thread-Id, X-Client-Request-Id)
  7. Body session_id / sessionId (root or nested request)
  8. Body metadata.user_id (non-Claude Code format)
  9. Body conversation_id
  10. Hash-based fallback from message content

Note: The cache key includes provider scope, session ID, and model. Home dispatch supplies a stable cross-provider scope regardless of provider availability; direct selector calls default to the supplied provider. Models retain separate bindings.

func (*SessionAffinitySelector) Stop

func (s *SessionAffinitySelector) Stop()

Stop releases resources held by the selector.

type SessionAffinityStore added in v1.1.6

type SessionAffinityStore interface {
	LoadSessionBinding(context.Context, string) (SessionBinding, error)
	// LoadLatestSessionBinding returns the latest live selection across models
	// on the supplied real credential providers, without renewing its lease.
	LoadLatestSessionBinding(context.Context, string, []string) (SessionBinding, error)
	CompareAndSwapSessionBinding(context.Context, SessionAffinityCommit) (bool, error)
}

SessionAffinityStore provides authoritative reads and atomic conditional writes. A missing binding has an empty revision. Expired bindings retain their revision until deleted so stale writers cannot overwrite a newer binding.

type SessionBinding added in v1.1.6

type SessionBinding struct {
	AuthID    string
	Revision  string
	ExpiresAt time.Time
}

SessionBinding is an authoritative snapshot, including expired bindings. Revisions are opaque and must never be reused after deletion or expiration.

type SessionCache

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

SessionCache provides TTL-based session to auth mapping with automatic cleanup.

func NewSessionCache

func NewSessionCache(ttl time.Duration) *SessionCache

NewSessionCache creates a cache with the specified TTL. A background goroutine periodically cleans expired entries.

func (*SessionCache) CompareAndSwapSessionBinding added in v1.1.6

func (c *SessionCache) CompareAndSwapSessionBinding(ctx context.Context, commit SessionAffinityCommit) (bool, error)

CompareAndSwapSessionBinding prevents concurrent first requests from returning independently selected credentials, including after a binding has been evicted.

func (*SessionCache) Get

func (c *SessionCache) Get(sessionID string) (string, bool)

Get retrieves the auth ID bound to a session, if still valid. Does NOT refresh the TTL on access.

func (*SessionCache) GetAndRefresh

func (c *SessionCache) GetAndRefresh(sessionID string) (string, bool)

GetAndRefresh retrieves the auth ID bound to a session and refreshes TTL on hit. This extends the binding lifetime for active sessions.

func (*SessionCache) Invalidate

func (c *SessionCache) Invalidate(sessionID string)

Invalidate removes a specific session binding.

func (*SessionCache) InvalidateAuth

func (c *SessionCache) InvalidateAuth(authID string)

InvalidateAuth removes all sessions bound to a specific auth ID. Used when an auth becomes unavailable.

func (*SessionCache) LoadLatestSessionBinding added in v1.1.10

func (c *SessionCache) LoadLatestSessionBinding(ctx context.Context, sessionKey string, providers []string) (SessionBinding, error)

LoadLatestSessionBinding observes selection order, not completion or TTL refresh order.

func (*SessionCache) LoadSessionBinding added in v1.1.6

func (c *SessionCache) LoadSessionBinding(ctx context.Context, key string) (SessionBinding, error)

LoadSessionBinding implements the atomic binding store for standalone selectors.

func (*SessionCache) Set

func (c *SessionCache) Set(sessionID, authID string)

Set binds a session to an auth ID with TTL refresh.

func (*SessionCache) Stop

func (c *SessionCache) Stop()

Stop terminates the background cleanup goroutine safely and idempotently.

type StateMutation added in v1.1.10

type StateMutation uint8

StateMutation distinguishes shared state changes from observation-only writes.

const (
	StateMutationUnchanged StateMutation = iota
	// StateMutationChanged persists the auth and notifies peers to reload it.
	StateMutationChanged
	// StateMutationObservation persists a replay fence without notifying peers.
	// The storage revision must still advance to reject older snapshot saves.
	StateMutationObservation
)

type StateMutator added in v1.0.49

type StateMutator interface {
	MutateAuthState(ctx context.Context, id string, mutate func(auth *Auth) StateMutation) (*Auth, error)
}

StateMutator applies mutate to the authoritative auth under a row lock. Changed and observation-only mutations are persisted atomically; only changed mutations publish an auth event. The returned auth includes the storage revision.

type StateVersionSaver added in v1.0.67

type StateVersionSaver interface {
	SaveWithStateVersion(ctx context.Context, auth *Auth) (id string, stateVersion int64, err error)
}

StateVersionSaver is an optional Store capability that returns the revision accepted for a save. A zero revision means the snapshot was ignored as stale.

type Status

type Status string

Status represents the lifecycle state of an Auth entry.

const (
	// StatusUnknown means the auth state could not be determined.
	StatusUnknown Status = "unknown"
	// StatusActive indicates the auth is valid and ready for execution.
	StatusActive Status = "active"
	// StatusPending indicates the auth is waiting for an external action, such as MFA.
	StatusPending Status = "pending"
	// StatusRefreshing indicates the auth is undergoing a refresh flow.
	StatusRefreshing Status = "refreshing"
	// StatusError indicates the auth is temporarily unavailable due to errors.
	StatusError Status = "error"
	// StatusDisabled marks the auth as intentionally disabled.
	StatusDisabled Status = "disabled"
)

type StoppableSelector

type StoppableSelector interface {
	Selector
	Stop()
}

StoppableSelector is an optional interface for selectors that hold resources. Selectors that implement this interface will have Stop called during shutdown.

type Store

type Store interface {
	// List returns all auth records stored in the backend.
	List(ctx context.Context) ([]*Auth, error)
	// Save persists the provided auth record, replacing any existing one with same ID.
	Save(ctx context.Context, auth *Auth) (string, error)
	// Delete removes the auth record identified by id.
	Delete(ctx context.Context, id string) error
}

Store abstracts persistence of Auth state across restarts.

func GetTokenStore

func GetTokenStore() Store

GetTokenStore returns the globally registered token store.

type UpstreamResponse added in v1.0.72

type UpstreamResponse struct {
	Status int    `json:"status"`
	Body   []byte `json:"body"`
}

UpstreamResponse contains the exact HTTP response returned by a provider.

type WeightedRoundRobinSelector added in v1.0.75

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

WeightedRoundRobinSelector provides smooth weighted round-robin selection.

func (*WeightedRoundRobinSelector) Pick added in v1.0.75

func (s *WeightedRoundRobinSelector) Pick(ctx context.Context, provider, model string, opts 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