Documentation
¶
Overview ¶
Package providerusage owns profile-scoped, in-memory usage snapshots and collection lifetimes. Collectors read only resolved-route credentials; background intent never accesses the Keychain. Publication fences route and credential ownership, and stale retention never crosses accounts. The daemon supplies DefaultRegistry to NewService and owns Start, consent invalidation, and Shutdown.
Index ¶
- Constants
- func KeychainSupported() bool
- func ParseRetryAfter(value string, now time.Time) time.Time
- type Account
- type AccountSelector
- type Action
- type Amount
- type Balance
- type ClaudeCollector
- func (c *ClaudeCollector) ClearCredentials(profileID string)
- func (c *ClaudeCollector) Close() error
- func (c *ClaudeCollector) Collect(ctx context.Context, target Target, _ Intent, identity CredentialIdentity) (Snapshot, error)
- func (c *ClaudeCollector) ForgetTarget(target Target)
- func (c *ClaudeCollector) Identity(ctx context.Context, target Target, intent Intent) (CredentialIdentity, error)
- func (*ClaudeCollector) ProviderID() string
- func (*ClaudeCollector) SelectorKey(env []string) string
- func (c *ClaudeCollector) ValidateIdentity(_ context.Context, target Target, identity CredentialIdentity) error
- type ClaudeOption
- type CodexCollector
- func (c *CodexCollector) Collect(ctx context.Context, t Target, intent Intent, cred CredentialIdentity) (Snapshot, error)
- func (*CodexCollector) Identity(ctx context.Context, t Target, _ Intent) (CredentialIdentity, error)
- func (*CodexCollector) ProviderID() string
- func (*CodexCollector) SelectorKey([]string) string
- type CodexOptions
- type Collector
- type CollectorOption
- type Confidence
- type CredentialCache
- type CredentialIdentity
- type CredentialProbe
- type CursorCollector
- func (c *CursorCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
- func (c *CursorCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
- func (*CursorCollector) ProviderID() string
- func (*CursorCollector) SelectorKey(env []string) string
- type Envelope
- type ErrorCode
- type GeminiCollector
- func (c *GeminiCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
- func (c *GeminiCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
- func (*GeminiCollector) ProviderID() string
- func (*GeminiCollector) SelectorKey(env []string) string
- type HTTPClient
- type Intent
- type KeychainReader
- type KimiCollector
- func (c *KimiCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
- func (c *KimiCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
- func (c *KimiCollector) ProviderID() string
- func (c *KimiCollector) SelectorKey([]string) string
- type Manager
- func (s *Manager) BootID() string
- func (s *Manager) ClearCredentials(profileID, collectorID string)
- func (s *Manager) Envelope(ctx context.Context, profile string) (Envelope, error)
- func (s *Manager) Refresh(ctx context.Context, req RefreshRequest) (Envelope, error)
- func (s *Manager) SetEnabled(ctx context.Context, enabled bool) error
- func (s *Manager) SetRefreshInterval(interval time.Duration)
- func (s *Manager) Shutdown(ctx context.Context) error
- func (s *Manager) Start(ctx context.Context, profileIDs []string) error
- func (s *Manager) Subscribe(profile string) (<-chan Revision, func())
- type Metrics
- type OpenRouterCollector
- type Options
- type PublicationValidator
- type RefreshRequest
- type Registry
- type RegistryOptions
- type ResolvedRoute
- type Revision
- type Service
- type Severity
- type Snapshot
- type Source
- type SourceKind
- type SpendCap
- type Status
- type Target
- type TargetCatalog
- type TargetCredentialCache
- type TargetResolver
- type TraySignal
- type UsageError
- type VercelCollector
- type Window
- type WindowKind
- type ZaiCollector
Constants ¶
const MaxResponseBytes = 1 << 20
Variables ¶
This section is empty.
Functions ¶
func KeychainSupported ¶
func KeychainSupported() bool
KeychainSupported reports whether the daemon host has the Claude Keychain source.
Types ¶
type AccountSelector ¶
AccountSelector is implemented by native-CLI collectors whose account is chosen by a route variable. SelectorKey names the variable an alias's own launch command must assign for env, after the collector's precedence: the dedicated account variable even when the lookup would fall back to its HOME-derived default (Claude, Codex, Kimi CLI), or the variable a home-based collector reads (Cursor, Gemini). It must share that precedence with the credential lookup. "" means the collector has no such variable.
type ClaudeCollector ¶
type ClaudeCollector struct {
// contains filtered or unexported fields
}
func NewClaudeCollector ¶
func NewClaudeCollector(options ...ClaudeOption) *ClaudeCollector
func (*ClaudeCollector) ClearCredentials ¶
func (c *ClaudeCollector) ClearCredentials(profileID string)
func (*ClaudeCollector) Close ¶
func (c *ClaudeCollector) Close() error
func (*ClaudeCollector) Collect ¶
func (c *ClaudeCollector) Collect( ctx context.Context, target Target, _ Intent, identity CredentialIdentity, ) (Snapshot, error)
func (*ClaudeCollector) ForgetTarget ¶
func (c *ClaudeCollector) ForgetTarget(target Target)
ForgetTarget drops a removed provider's cached token, such as a deleted Claude alias.
func (*ClaudeCollector) Identity ¶
func (c *ClaudeCollector) Identity(ctx context.Context, target Target, intent Intent) (CredentialIdentity, error)
func (*ClaudeCollector) ProviderID ¶
func (*ClaudeCollector) ProviderID() string
func (*ClaudeCollector) SelectorKey ¶
func (*ClaudeCollector) SelectorKey(env []string) string
SelectorKey implements AccountSelector: a present CLAUDE_SECURESTORAGE_CONFIG_DIR takes precedence over CLAUDE_CONFIG_DIR for the credential lookup.
func (*ClaudeCollector) ValidateIdentity ¶
func (c *ClaudeCollector) ValidateIdentity(_ context.Context, target Target, identity CredentialIdentity) error
ValidateIdentity never reads the Keychain, including for an explicit one-shot collection.
type ClaudeOption ¶
type ClaudeOption func(*ClaudeCollector)
func WithClaudeClock ¶
func WithClaudeClock(now func() time.Time) ClaudeOption
func WithClaudeHTTP ¶
func WithClaudeHTTP(baseURL string, transport http.RoundTripper) ClaudeOption
func WithClaudeKeychain ¶
func WithClaudeKeychain(reader KeychainReader) ClaudeOption
func WithClaudePlatform ¶
func WithClaudePlatform(platform string) ClaudeOption
WithClaudePlatform overrides the host platform for collectors with an injected Keychain reader.
type CodexCollector ¶
type CodexCollector struct {
// contains filtered or unexported fields
}
func NewCodexCollector ¶
func NewCodexCollector(options CodexOptions) *CodexCollector
func (*CodexCollector) Collect ¶
func (c *CodexCollector) Collect( ctx context.Context, t Target, intent Intent, cred CredentialIdentity, ) (Snapshot, error)
func (*CodexCollector) Identity ¶
func (*CodexCollector) Identity(ctx context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*CodexCollector) ProviderID ¶
func (*CodexCollector) ProviderID() string
func (*CodexCollector) SelectorKey ¶
func (*CodexCollector) SelectorKey([]string) string
SelectorKey implements AccountSelector.
type CodexOptions ¶
type CodexOptions struct {
BaseURL string
Transport http.RoundTripper
Now func() time.Time
}
type Collector ¶
type Collector interface {
ProviderID() string
CredentialProbe
// Errors may carry fenced partial data without MeasuredAt; same-owner last-good data takes precedence.
Collect(ctx context.Context, t Target, intent Intent, cred CredentialIdentity) (Snapshot, error) // *UsageError
}
Collector produces one snapshot for a target using the credential the probe identified.
type CollectorOption ¶
type CollectorOption func(*collectorHTTP)
func WithCollectorBaseURL ¶
func WithCollectorBaseURL(baseURL string) CollectorOption
func WithCollectorClock ¶
func WithCollectorClock(now func() time.Time) CollectorOption
func WithCollectorTransport ¶
func WithCollectorTransport(transport http.RoundTripper) CollectorOption
type Confidence ¶
type Confidence string
const ( ConfidenceExact Confidence = "exact" ConfidencePercentOnly Confidence = "percent_only" ConfidenceEstimated Confidence = "estimated" )
type CredentialCache ¶
type CredentialCache interface {
// An empty profile ID clears every cached profile.
ClearCredentials(profileID string)
}
type CredentialIdentity ¶
type CredentialIdentity struct {
Digest [32]byte `json:"-"` // HMAC-SHA256(process-random key, source kind || credential bytes)
AccountID string `json:"-"` // upstream account ID when readable without network; "" otherwise
}
CredentialIdentity fences publication and keys cooldowns. Never serialized, logged, or exposed.
func NewCredentialIdentity ¶
func NewCredentialIdentity(source SourceKind, credential []byte, accountID string) CredentialIdentity
func (CredentialIdentity) LogValue ¶
func (CredentialIdentity) LogValue() slog.Value
func (CredentialIdentity) Same ¶
func (a CredentialIdentity) Same(b CredentialIdentity) bool
type CredentialProbe ¶
type CredentialProbe interface {
Identity(ctx context.Context, t Target, intent Intent) (CredentialIdentity, error) // *UsageError
}
CredentialProbe reads the route's credential without network access.
type CursorCollector ¶
type CursorCollector struct {
// contains filtered or unexported fields
}
func NewCursorCollector ¶
func NewCursorCollector(options ...CollectorOption) *CursorCollector
func (*CursorCollector) Collect ¶
func (c *CursorCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
func (*CursorCollector) Identity ¶
func (c *CursorCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*CursorCollector) ProviderID ¶
func (*CursorCollector) ProviderID() string
func (*CursorCollector) SelectorKey ¶
func (*CursorCollector) SelectorKey(env []string) string
SelectorKey implements AccountSelector.
type ErrorCode ¶
type ErrorCode string
const ( ErrorCodeProfileNotFound ErrorCode = "profile_not_found" ErrorCodeProfileSessionConflict ErrorCode = "profile_session_conflict" ErrorCodeInvalidRequest ErrorCode = "invalid_request" ErrorCodeAppTokenRouteForbidden ErrorCode = "app_token_route_forbidden" //nolint:gosec // Public error code. ErrorCodeProviderNotFound ErrorCode = "provider_not_found" ErrorCodeProviderUsageDisabled ErrorCode = "provider_usage_disabled" ErrorCodeAuthMissing ErrorCode = "auth_missing" ErrorCodeAuthExpired ErrorCode = "auth_expired" ErrorCodeAuthScope ErrorCode = "auth_scope" ErrorCodeKeychainConsentRequired ErrorCode = "keychain_consent_required" ErrorCodeKeychainDenied ErrorCode = "keychain_denied" ErrorCodeKeychainReadTimeout ErrorCode = "keychain_read_timeout" ErrorCodeKeychainTokenExpired ErrorCode = "keychain_token_expired" ErrorCodeProviderRateLimited ErrorCode = "provider_rate_limited" ErrorCodeNetworkError ErrorCode = "network_error" ErrorCodeParseError ErrorCode = "parse_error" ErrorCodeNoCollector ErrorCode = "no_collector" ErrorCodeNoPlan ErrorCode = "no_plan" ErrorCodeAuthStoreUnsupported ErrorCode = "auth_store_unsupported" ErrorCodeDisabled ErrorCode = "disabled" )
type GeminiCollector ¶
type GeminiCollector struct {
// contains filtered or unexported fields
}
func NewGeminiCollector ¶
func NewGeminiCollector(options ...CollectorOption) *GeminiCollector
func (*GeminiCollector) Collect ¶
func (c *GeminiCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
func (*GeminiCollector) Identity ¶
func (c *GeminiCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*GeminiCollector) ProviderID ¶
func (*GeminiCollector) ProviderID() string
func (*GeminiCollector) SelectorKey ¶
func (*GeminiCollector) SelectorKey(env []string) string
SelectorKey implements AccountSelector.
type HTTPClient ¶
type HTTPClient struct {
// contains filtered or unexported fields
}
HTTPClient confines authenticated requests to their original origin.
func NewHTTPClient ¶
func NewHTTPClient(baseURL string, transport http.RoundTripper, now func() time.Time) *HTTPClient
type KeychainReader ¶
type KimiCollector ¶
type KimiCollector struct {
// contains filtered or unexported fields
}
func NewKimiCLICollector ¶
func NewKimiCLICollector(options ...CollectorOption) *KimiCollector
func NewKimiCollector ¶
func NewKimiCollector(options ...CollectorOption) *KimiCollector
func (*KimiCollector) Collect ¶
func (c *KimiCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
func (*KimiCollector) Identity ¶
func (c *KimiCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*KimiCollector) ProviderID ¶
func (c *KimiCollector) ProviderID() string
func (*KimiCollector) SelectorKey ¶
func (c *KimiCollector) SelectorKey([]string) string
SelectorKey implements AccountSelector for the Kimi CLI; Moonshot binds an API key instead.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
func NewService ¶
func (*Manager) ClearCredentials ¶
ClearCredentials invalidates a collector family's cache and every snapshot it owns, including configured aliases that collect through the family, after consent changes.
func (*Manager) SetEnabled ¶
SetEnabled drops all cached values and joins canceled flights before returning on disable.
func (*Manager) SetRefreshInterval ¶
SetRefreshInterval reschedules from now; intervals outside [1m, 1h] are ignored. Startup jitter, error outcomes, and active cooldown deadlines are preserved.
type OpenRouterCollector ¶
type OpenRouterCollector struct {
// contains filtered or unexported fields
}
func NewOpenRouterCollector ¶
func NewOpenRouterCollector(options ...CollectorOption) *OpenRouterCollector
func (*OpenRouterCollector) Collect ¶
func (c *OpenRouterCollector) Collect( ctx context.Context, t Target, _ Intent, cred CredentialIdentity, ) (Snapshot, error)
func (*OpenRouterCollector) Identity ¶
func (*OpenRouterCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*OpenRouterCollector) ProviderID ¶
func (*OpenRouterCollector) ProviderID() string
type PublicationValidator ¶
type PublicationValidator interface {
ValidateIdentity(ctx context.Context, t Target, captured CredentialIdentity) error
}
PublicationValidator validates one-shot credentials without loading them again.
type RefreshRequest ¶
type RefreshRequest struct {
ProfileID string
ProviderIDs []string // empty = all targets
MaxAge time.Duration // refresh only snapshots older than max(MaxAge, 30s floor)
Wait time.Duration // caller wait for results (zero returns immediately, max 30s); never bounds the flight
Intent Intent // decided by the API boundary from principal + requested intent
}
type Registry ¶
func DefaultRegistry ¶
func DefaultRegistry(options RegistryOptions) Registry
DefaultRegistry constructs the supported collectors without probing credentials or providers.
type RegistryOptions ¶
type RegistryOptions struct {
BaseURLs map[string]string
Transport http.RoundTripper
Now func() time.Time
Keychain KeychainReader
}
type ResolvedRoute ¶
type ResolvedRoute struct {
Env []string // effective provider env (home/config dir), secrets excluded
NativeCommand string // resolved native CLI path when the provider has one ("" if absent)
BoundSecrets map[string]string // slot -> value, only slots declared by the provider
KeychainAccess bool // operator consent recorded in config
}
ResolvedRoute is the read-only launch context a collector may use.
type Service ¶
type Service interface {
Envelope(ctx context.Context, profileID string) (Envelope, error)
Refresh(ctx context.Context, req RefreshRequest) (Envelope, error)
Subscribe(profileID string) (<-chan Revision, func())
}
Service is the daemon-owned read model.
type Snapshot ¶
type Snapshot struct {
ProviderID string
CollectorID string // collector family when it differs from ProviderID (an alias); "" otherwise
ProviderName string
Status Status
Source *Source // nil before first success
Account *Account
Windows []Window
Balances []Balance
SpendCaps []SpendCap
Confidence Confidence // exact | percent_only | estimated
MeasuredAt *time.Time // when the provider measured / we received accepted data
CheckedAt *time.Time // last attempt, success or failure
NextRefreshAt *time.Time
Refreshing bool // a collection for this target is in flight
Error *UsageError
// contains filtered or unexported fields
}
type Source ¶
type Source struct {
Kind SourceKind // cli_rpc | oauth_http | api_key_http | acp_observed
Label string // "Codex app-server", "Claude Code OAuth", "OpenRouter API key"
}
type SourceKind ¶
type SourceKind string
const ( SourceKindCLIRPC SourceKind = "cli_rpc" SourceKindOAuthHTTP SourceKind = "oauth_http" SourceKindAPIKeyHTTP SourceKind = "api_key_http" //nolint:gosec // Public source-kind identifier, not a credential. SourceKindACPObserved SourceKind = "acp_observed" )
type Status ¶
type Status string
const ( StatusOK Status = "ok" StatusStale Status = "stale" StatusRefreshing Status = "refreshing" StatusSignedOut Status = "signed_out" StatusNeedsConsent Status = "needs_consent" StatusRateLimited Status = "rate_limited" StatusError Status = "error" StatusUnsupported Status = "unsupported" StatusDisabled Status = "disabled" )
type Target ¶
type Target struct {
ProfileID string
ProviderID string // canonical Compozy provider ID
CollectorID string // collector family; empty means ProviderID (aliases resolve via runtime_provider)
ProviderName string // catalog display name
AuthRouteFingerprint string
RouteFingerprint string // daemon-derived; never caller-supplied
Status Status // Empty means eligible for collection.
Error *UsageError
Route ResolvedRoute
}
Target is one profile-scoped provider route whose usage is collected.
type TargetCatalog ¶
type TargetCatalog struct {
// contains filtered or unexported fields
}
TargetCatalog provides atomic profile route replacement for configuration-driven composition.
func (*TargetCatalog) Replace ¶
func (c *TargetCatalog) Replace(profile string, targets []Target)
type TargetCredentialCache ¶
type TargetCredentialCache interface {
ForgetTarget(t Target)
}
TargetCredentialCache evicts the cached credential of one target that left the catalog.
type TargetResolver ¶
TargetResolver lists the enabled targets for one profile.
type TraySignal ¶
type TraySignal struct {
ProviderID string
WindowID string
Label string // "Codex · Weekly"
UsedPercent float64
ResetsAt *time.Time
Severity Severity // neutral | warning | exhausted
Stale bool
}
func SelectTray ¶
func SelectTray(targets []Snapshot) *TraySignal
type UsageError ¶
type UsageError struct {
Code ErrorCode // see _dx.md Errors
Message string // redacted, operator-readable
Action string // "sign_in" | "allow_keychain" | "refresh" | "retry" | "configure" | ""
RetryAfter *time.Time
}
func AsUsageError ¶
func AsUsageError(err error, provider string) *UsageError
func NewUsageError ¶
func NewUsageError(code ErrorCode, provider string) *UsageError
NewUsageError never includes upstream error text or response bodies.
func RateLimited ¶
func RateLimited(provider string, until time.Time) *UsageError
func (*UsageError) Error ¶
func (e *UsageError) Error() string
func (*UsageError) Status ¶
func (e *UsageError) Status() Status
type VercelCollector ¶
type VercelCollector struct {
// contains filtered or unexported fields
}
func NewVercelCollector ¶
func NewVercelCollector(options ...CollectorOption) *VercelCollector
func (*VercelCollector) Collect ¶
func (c *VercelCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
func (*VercelCollector) Identity ¶
func (*VercelCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*VercelCollector) ProviderID ¶
func (*VercelCollector) ProviderID() string
type Window ¶
type Window struct {
ID string // stable per provider: "session", "weekly", "weekly_opus", "model:<slug>:weekly", "monthly"
Label string // "Session", "Weekly", "Weekly · Opus"
Kind WindowKind // session | daily | weekly | monthly | model | other
DurationSeconds *int64
UsedPercent *float64 // nil = unknown
Used *Amount // optional raw counts when the provider reports them
Limit *Amount
ResetsAt *time.Time
ResetText string // provider text when no timestamp exists
}
type WindowKind ¶
type WindowKind string
const ( WindowKindSession WindowKind = "session" WindowKindDaily WindowKind = "daily" WindowKindWeekly WindowKind = "weekly" WindowKindMonthly WindowKind = "monthly" WindowKindModel WindowKind = "model" WindowKindOther WindowKind = "other" )
type ZaiCollector ¶
type ZaiCollector struct {
// contains filtered or unexported fields
}
func NewZaiCollector ¶
func NewZaiCollector(options ...CollectorOption) *ZaiCollector
func (*ZaiCollector) Collect ¶
func (c *ZaiCollector) Collect(ctx context.Context, t Target, _ Intent, cred CredentialIdentity) (Snapshot, error)
func (*ZaiCollector) Identity ¶
func (*ZaiCollector) Identity(_ context.Context, t Target, _ Intent) (CredentialIdentity, error)
func (*ZaiCollector) ProviderID ¶
func (*ZaiCollector) ProviderID() string
Source Files
¶
- accounts.go
- catalog.go
- claude.go
- claude_credentials.go
- claude_http.go
- claude_keychain_other.go
- claude_mapping.go
- codex.go
- codex_decode.go
- codex_rpc.go
- collector_amount.go
- collector_credentials.go
- collector_cursor.go
- collector_gemini.go
- collector_http.go
- collector_kimi.go
- collector_openrouter.go
- collector_vercel.go
- collector_zai.go
- constants.go
- doc.go
- errors.go
- flight.go
- http.go
- identity.go
- interfaces.go
- lifecycle.go
- models.go
- options.go
- publication.go
- read_fence.go
- registry.go
- service.go
- snapshot.go