# `Image.Plug.Provider`
[🔗](https://github.com/elixir-image/image_plug/blob/v0.1.0/lib/image/plug/provider.ex#L1)

Behaviour for URL-API providers.

A provider parses an inbound `Plug.Conn` into a canonical
`Image.Plug.Pipeline` plus an `Image.Plug.Source` reference. It
may also resolve the request to a named variant lookup or to a
passthrough that streams the source unchanged.

Providers are stateless. All configuration is passed in by
`Image.Plug` as the second argument to `c:parse/2`.

# `info_kind`

```elixir
@type info_kind() :: :iiif_image_info
```

The shape returned by `c:parse/2` on success.

* `{:pipeline, pipeline, source}` — fully-formed pipeline; resolve
  the source and execute.

* `{:variant, name, overrides, source}` — look up the variant by
  name in the configured `Image.Plug.VariantStore`, then merge
  overrides on top before executing.

* `{:passthrough, source}` — no transforms. The plug streams the
  source unchanged.

* `{:info, info_kind, source}` — the request is for a metadata
  document (currently only `:iiif_image_info` for the IIIF Image
  API 3.0 `info.json`). The plug builds the document by reading
  the source's dimensions and serialises as JSON.

# `override`

```elixir
@type override() :: {atom(), term()}
```

An override applied on top of a resolved variant. The provider
produces these from per-request options that should win over the
stored variant's defaults.

# `result`

```elixir
@type result() ::
  {:pipeline, Image.Plug.Pipeline.t(), Image.Plug.Source.t()}
  | {:variant, name :: String.t(), [override()], Image.Plug.Source.t()}
  | {:passthrough, Image.Plug.Source.t()}
  | {:info, info_kind(), Image.Plug.Source.t()}
```

# `parse`

```elixir
@callback parse(Plug.Conn.t(), options :: keyword()) ::
  {:ok, result()} | {:error, Image.Plug.Error.t()}
```

Parses a request into one of the `t:result/0` shapes.

Implementations must be pure URL/header parsing. They must not fetch
source bytes or look up variants — those are the responsibilities of
`Image.Plug.SourceResolver` and `Image.Plug.VariantStore`.

Implementations must not raise on malformed input; return a tagged
`Image.Plug.Error` instead.

---

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