# `Stevedore.Auth.Cache`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/auth/cache.ex#L1)

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)

# `key`

```elixir
@type key() :: {registry :: String.t(), scope :: String.t()}
```

A cache entry's key: the registry host and the auth scope the token is valid for.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear`

```elixir
@spec clear(Agent.agent()) :: :ok
```

Drops all cached tokens.

# `get`

```elixir
@spec get(Agent.agent(), key()) :: {:ok, String.t()} | :miss
```

Returns `{:ok, token}` for `key`, or `:miss` when it is absent or expired.

# `put`

```elixir
@spec put(Agent.agent(), key(), String.t(), non_neg_integer() | :default) :: :ok
```

Caches `token` under `key`.

`ttl` is the lifetime in milliseconds, or `:default` to use the cache's configured `:ttl`.

# `start_link`

```elixir
@spec start_link(keyword()) :: Agent.on_start()
```

Starts a token cache.

Options: `:name` (register the process under a name) and `:ttl` (token lifetime in
milliseconds, default `60000`). Other options are passed to `Agent.start_link/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*