# `ImagePipe.Source.CacheSettings`
[🔗](https://github.com/hlindset/image_pipe/blob/v0.2.0/image_pipe/lib/image_pipe/source/cache_settings.ex#L1)

Cache settings shared by source adapters.

The built-in adapters accept these options, and a custom adapter can append
`schema/0` to its own option schema to accept them too:

    @schema NimbleOptions.new!([bucket: [type: :string, required: true]] ++ CacheSettings.schema())

After validating, `validate/1` rejects a lifetime or stale window on an
immutable source. `fields/2` then turns the validated options into the
cache fields of `ImagePipe.Source.Resolved`. Their effect is explained in
[Caching and freshness](caching-and-freshness.md).

## Options

* `:stable` (`:auto` or `:immutable`) - `:immutable` marks an immutable source: an identifier always names the same bytes, so its originals and processed images never expire and are never revalidated. With `:auto`, each original is identified by its content. See [immutable sources](caching-and-freshness.md#immutable-sources). The default value is `:auto`.

* `:cache_policy` (`t:keyword/0`) - Cache policy for this source, with the fields of `ImagePipe.Source.CachePolicy`. Each field it sets replaces that field of the `:source_cache_policy` of `ImagePipe.config/1`. A source with `stable: :immutable` can't set a `:freshness` duration or a `:stale_while_revalidate` window. The default value is `[]`.

* `:internal_cache` (`:enabled` or `:disabled`) - `:disabled` keeps this source's originals and processed images out of the caches, including images that use this source for a watermark. `:enabled` caches what the source's storage policy allows. The default value is `:enabled`.

* `:http_cache` (`:inherit`, `:validators`, `:auto`, `:public`, or `:private`) - HTTP cache headers for responses from this source. `:inherit` uses the mount's `:http_cache` (see `ImagePipe.Plug`), and any other value replaces it. See [per-source modes](cdn-http-cache.md#per-source-modes). The default value is `:inherit`.

# `fields`

```elixir
@spec fields(keyword(), keyword()) :: keyword()
```

Returns the `:internal_cache`, `:http_cache`, and `:cache_semantics` fields
of `ImagePipe.Source.Resolved`.

Takes the validated options and:

  * `:stable?` - whether this source's bytes can't change, either because
    the options trust it or because the source itself pins them.
  * `:seed` - the byte-identity seed used when the source is stable. It must
    not contain secrets.
  * `:copy?` - whether to keep a local copy of the original in the input
    pool. Remote adapters pass `true`.

A source that isn't stable is identified by its content.

# `immutable?`

```elixir
@spec immutable?(keyword()) :: boolean()
```

Whether the options mark the source as immutable.

# `schema`

```elixir
@spec schema() :: keyword()
```

NimbleOptions schema entries for the shared cache settings.

# `validate`

```elixir
@spec validate(keyword()) ::
  {:ok, keyword()} | {:error, {:invalid_source_config, String.t()}}
```

Rejects a TTL or stale-while-revalidate window on an immutable source, which
has no freshness deadline. Returns the options unchanged when valid.

---

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