The contract a variant store backend implements, and the dispatch to the configured one.

A completed render is written back under its cache key so the next request for the same variant is served from storage instead of re-rendered. Where that storage is — a local directory, an S3 bucket — is a backend behind this behaviour, selected by the scheme of AP_VARIANT_STORE:

scheme     module                          slice
file://    AudioProxy.VariantStore.Local   add-variant-store
s3://      AudioProxy.VariantStore.S3      add-s3-variant-store

The shape deliberately mirrors AudioProxy.Source.Type: one module per scheme, five callbacks, and a new backend is a registration rather than an edit to the render path. Cache behaviour never depends on where source audio comes from — a file:// store caches renders of s3:// sources and vice versa.

The callbacks, in the order a request meets them

• head/1 — is this variant stored, and what would serving it need to know? The HIT check.
• get_stream/2 — the bytes, or a Range slice of them, as a lazy stream. Proxy-mode serving.
• presign/2 — a URL the client can be redirected to. Redirect-mode serving, and only for backends that advertise it (see below).
• put_stream/3 — the write-back: bytes plus the response metadata they must be served with.
• capabilities/0 — what this backend can do beyond the mandatory four.

Metadata travels with the bytes

put_stream/3 takes a metadata/0 because a store that keeps only bytes cannot serve a redirected fetch correctly: a player handed application/octet-stream may refuse to decode it. Every backend persists the metadata; a backend that cannot attach it to a direct fetch (the redirect case) simply does not advertise :presign, and AudioProxy.Config refuses AP_SERVE_MODE=redirect against it at boot.

Atomic or absent

A put_stream/3 that does not run to completion — the render failed, the write errored — must leave nothing readable under the key. Each backend implements that with whatever its storage offers: the local backend stages into a temp file inside the store and File.rename/2s on completion; the S3 backend gets it from the protocol, since an object does not exist until its upload completes and a failed multipart is aborted. head/1 answering {:ok, _} therefore always means the whole variant, with its metadata.