authrefresh

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package authrefresh keeps a provider credential usable without depending on the host's own refresh loop.

CPA does run an auto-refresh loop, but it starts with the process (`sdk/cliproxy/service_lifecycle.go`: StartAutoRefresh(ctx, 15*time.Minute)) and every restart resets its clock — and every plugin deploy restarts the process. A credential that expires inside a churny window is therefore never refreshed by the host: the first tick lands after the token is already dead, while requests that arrive in between keep using the expired bytes. That is exactly the state the CodeArts status page used to be in — the balance read answered "the security token has expired" while the same card still claimed 可自动续期, because the host timer that would have renewed it never fired.

The remedy belongs in the plugin, because the plugin is the layer that is asked to *use* the credential. Before a credential is used — to read a quota, to sign an inference call — the plugin checks the credential's own expiry and, when it is expired or close to expiring, renews it through the provider's own `auth.refresh` handler and writes the result back to the auth file the host already knows.

Four rules shape the behaviour:

  • no usable expiry means no action. A credential that carries no parsable expiry is left exactly as it is; inventing one would renew it forever.
  • a short cooldown bounds the attempt rate, and a per-credential single-flight makes concurrent callers share one vendor call, so a page load plus an inference request cannot stampede the refresh endpoint.
  • a terminal failure (the vendor saying the renewal grant is dead — the 401/403 the provider handlers already attach to it) marks the credential dead: no further attempt until its bytes change. A transport failure is never terminal, and is never reported as an expired credential.
  • the refreshed credential is persisted through host.auth.save under the same file name, so a refresh can neither mint a second auth file nor lose the one the host is refreshing.

Index

Constants

View Source
const DefaultCooldown = 5 * time.Minute

DefaultCooldown is the gap enforced between two refresh attempts on the same credential. It is deliberately longer than a page load: the status page and the executor both call Ensure, and a credential that cannot be renewed must not turn every request into another vendor call.

Variables

This section is empty.

Functions

func IsTerminal

func IsTerminal(err error) bool

IsTerminal reports whether a refresh failure ends the credential's life.

The repo's providers already make that call: a renewal grant that is dead is answered with a 401/403 (and a `refresh_token_expired`/`session_dead`-style code), while a transport failure, a 5xx or a 429 is not. This function only reads that existing classification — it never invents one, so a transport failure can never be reported as an expired credential.

Types

type Policy

type Policy struct {
	// Provider is the provider key, used in log lines and in the refresh
	// request the handler receives.
	Provider string
	// Lead is how long before its expiry a credential is renewed. It is the
	// same window the provider already reports to the host through
	// NextRefreshAfter.
	Lead time.Duration
	// LeadFunc, when set, is read on every check instead of Lead. A provider
	// whose lead window is a live setting uses it, so a settings change takes
	// effect without rebuilding the refresher (and without racing a request).
	LeadFunc func() time.Duration
	// Cooldown is the minimum gap between two attempts on one credential.
	// Zero means DefaultCooldown.
	Cooldown time.Duration
	// Expiry reads the credential's own expiry. ok is false when the credential
	// carries no usable one; such a credential is never refreshed. It must not
	// invent a fallback: a fabricated expiry is a refresh loop.
	Expiry func(storage json.RawMessage) (expiry time.Time, ok bool)
	// Refreshable reports whether the credential can be renewed at all — a
	// ticket-flow credential without a refresh token cannot, and is left alone.
	// Nil means "renewable whenever Expiry says the credential is due".
	Refreshable func(storage json.RawMessage) bool
	// Refresh renews the credential. Nil means this provider has no refresh
	// path at all (Loomy's `auth.refresh` is a validity probe): Ensure then
	// never touches the vendor.
	Refresh RefreshFunc
}

Policy is one provider's credential-freshness rules.

type RefreshFunc

RefreshFunc performs one renewal for a provider. It is the provider's own `auth.refresh` handler, adapted with Handler, so the in-plugin path and the host-driven path can never drift apart.

func Handler

func Handler(handler func(h *abiboot.Host, raw json.RawMessage) (any, error)) RefreshFunc

Handler adapts a provider's own `auth.refresh` method handler into a RefreshFunc. The in-plugin refresh therefore runs exactly the code the host would have run, which is what keeps one provider from having two renewal implementations.

type Refresher

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

Refresher applies one Policy. It holds the per-credential cooldown and single-flight state, so a provider creates exactly one (package level) and shares it between its page and its executor.

func New

func New(policy Policy) *Refresher

New returns a Refresher for one provider.

func (*Refresher) Ensure

func (r *Refresher) Ensure(h *abiboot.Host, request Request) (Result, error)

Ensure makes sure a credential is still usable before a caller uses it, and returns the bytes to use.

It fails only when a refresh was needed and did not produce a usable credential; the error is the provider's own, so its message and its HTTP status stay exactly as the provider classified them. Result.Expired says whether those bytes are past their expiry anyway, which is how a caller tells "renewal failed but the token still works" from "this credential is dead until the user logs in again". The failure is also carried in Result.Err, so a caller that keeps the result can render it later.

func (*Refresher) EnsureUsable

func (r *Refresher) EnsureUsable(h *abiboot.Host, request Request) (Result, error)

EnsureUsable is Ensure plus the rule every caller that is about to USE a credential follows.

A renewal that failed only stops the caller when the credential is already past its expiry: the honest reason for a failure is then the renewal failure, never a doomed upstream call reporting "the security token has expired". A credential that is merely inside the lead window is still usable, so a transport failure must not fail the request — it is logged, and the caller proceeds with the credential it already had.

type Request

type Request struct {
	// Name is the auth file name the host already knows for this credential:
	// the `FileName` of `auth.parse`, the record id of an executor request, or
	// the entry name of a listing. It is both the identity used for
	// cooldown/single-flight and the name the refreshed credential is written
	// back to. An empty name falls back to the name the provider derives.
	Name string
	// StorageJSON is the credential exactly as the host supplied it.
	StorageJSON json.RawMessage
	// Attributes carries the credential's host attributes (`path`, `source`)
	// so the provider can still resolve a name when Name is empty.
	Attributes map[string]string
}

Request names one credential and carries the bytes the host handed over.

type Result

type Result struct {
	// Storage is the credential to use: the refreshed bytes when Refreshed is
	// true, the caller's own bytes otherwise. It is never empty when the caller
	// supplied a credential.
	Storage json.RawMessage
	// Refreshed reports that the vendor issued a new credential and it was
	// written back through host.auth.save.
	Refreshed bool
	// Attempted reports that a refresh was tried — by this call, or by the
	// in-flight call it joined. It is false when the credential was left alone
	// or when the cooldown suppressed the attempt.
	Attempted bool
	// Expired reports that Storage is already past its own expiry. A caller
	// that also received an error must not use it.
	Expired bool
	// Dead reports that the provider called this credential's renewal terminal.
	// No further attempt is made until the credential bytes change.
	Dead bool
	// Err is the renewal failure, or nil. It is the same value Ensure returns,
	// carried here so a caller that keeps the result — a status page, for
	// instance — can report what happened without a second field.
	Err error
}

Result reports what Ensure did and which bytes the caller should use.

Jump to

Keyboard shortcuts

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