An opt-in, in-process cache of registry bearer tokens, keyed by {registry, scope}.

By default Stevedore.Registry re-runs the 401 → token handshake on every request. Start a cache and pass it as the :token_cache option to reuse a token across the manifest + blob fetches of a pull: the first request earns the token, the rest send it preemptively — skipping both the 401 and the token-endpoint round-trip. A stale or rejected token still falls back to a fresh handshake, so the cache never changes results, only request count.

Tokens are cached for :ttl milliseconds (default 60s, comfortably inside a typical registry token lifetime); the 401 fallback covers any token that expires sooner. Starting a cache is the consumer's choice — nothing here runs unless you start it, preserving Stevedore's weightless-by-default invariant.

Example

{:ok, cache} = Stevedore.Auth.Cache.start_link([])
Stevedore.copy("docker://alpine:3.20", "oci:./alpine:3.20", token_cache: cache)