Documentation
¶
Index ¶
Constants ¶
const DefaultRefreshInterval = 5 * time.Minute
DefaultRefreshInterval is the base poll cadence. The IAM endpoint advertises Cache-Control: public, max-age=300 — we match it. Real refreshes are jittered ±15% to spread load when many resource servers boot at once.
Variables ¶
var ErrNoKeys = errors.New("capauth/registry: IAM returned empty key list")
ErrNoKeys is returned by Refresh when the IAM endpoint returns an empty key list. The local table is preserved (not cleared) — a deployment glitch must not turn off all auth.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Endpoint is the base URL of the IAM service, e.g.
// "https://iam.hanzo.ai". The /v1/iam/cap/issuer-keys path is
// appended.
Endpoint string
// HTTPClient is the http.Client used for polls. Defaults to
// http.DefaultClient. Tests inject one wired to httptest.NewServer.
HTTPClient *http.Client
// RefreshInterval is the base poll cadence. Defaults to
// DefaultRefreshInterval (5 min). Tests pass shorter values.
RefreshInterval time.Duration
}
Config drives IAMClient. Only Endpoint is required.
type IAMClient ¶
type IAMClient struct {
// contains filtered or unexported fields
}
IAMClient implements capauth.IssuerRegistry by polling IAM.
Safe for concurrent use. The local map is guarded by an RWMutex; reads (Lookup) take a read lock and copy out the bytes; writes (Refresh) take a write lock and overwrite the map.
func New ¶
New constructs an IAMClient. Call Refresh once at boot, then Start to kick off the background refresh loop.
func (*IAMClient) Lookup ¶
Lookup satisfies capauth.IssuerRegistry. Returns the raw public-key bytes for hashedPub or cap.ErrIssuerUnknown. The returned slice is a fresh copy — safe for the caller to retain past the next Refresh.
func (*IAMClient) Refresh ¶
Refresh fetches the current issuer key list from IAM and replaces the local table. Returns nil on success, ErrNoKeys if the response is empty (and preserves the existing table), or a wrapped error on transport/parse failure (and preserves the existing table).
func (*IAMClient) Register ¶
Register exists to satisfy the full capauth.IssuerRegistry interface. In the polling-client mode it's a no-op — the source of truth is the IAM endpoint, not a caller-supplied key. We retain the method so the type still satisfies IssuerRegistry; callers that have an out-of-band key (e.g. for testing) should compose with a MemoryRegistry instead.
func (*IAMClient) Size ¶
Size returns the number of keys currently held. Useful for liveness checks: a zero-size registry is a verifier that can't verify anything.
func (*IAMClient) Start ¶
Start kicks off the background refresh loop. Returns a stop function; the loop exits when stop() is called OR when ctx is cancelled. The initial refresh runs synchronously inline (so callers can fail- fast at boot if IAM is unreachable); subsequent refreshes are async/jittered.
If the initial Refresh fails, Start returns the error. Callers should treat boot-time IAM unreachability as a hard failure — a verifier with no keys can't verify anything.
Source Files