# `ImagePipe.Plug`
[🔗](https://github.com/hlindset/image_pipe/blob/v0.2.0/image_pipe/lib/image_pipe/plug.ex#L1)

Serves ImagePipe's image API from a Plug or Phoenix router. Each place it is
plugged in is a mount, with its own options.

    forward "/images", ImagePipe.Plug, sources: [...]

In a `Plug.Router`, pass the options as `:init_opts`:

    forward "/images", to: ImagePipe.Plug, init_opts: [sources: [...]]

A mount answers `GET`, `HEAD`, and `OPTIONS`. Other methods get `405`.
[Getting started with Phoenix](phoenix-getting-started.md) walks through
setting up a mount.

An inline mount accepts every option of `ImagePipe.config/1`, or a
`:config` built with it, plus the mount options below. It can't start the
processes a cache needs, so `init/1` raises `ArgumentError` for a
configuration with `:cache` or `:input_cache`. To use a cache, read runtime
values, or share the configuration with `ImagePipe.run/4`, mount an
instance instead.

The URLs a mount serves are described in
[Requesting images](requesting-images.md).

## Mounting an instance

Phoenix evaluates `forward` options at compile time. When the configuration
reads runtime values, such as keys from environment variables, or uses a
cache, run it as an instance (see `ImagePipe.child_spec/1`) and
mount the instance by name:

    forward "/images", ImagePipe.Plug, instance: MyApp.Images, http_cache: :auto
    forward "/signed", ImagePipe.Plug, instance: MyApp.Images, mount: :signed

`mount: :signed` picks the URL settings named `signed` in the instance's
`:mounts`, such as `mounts: [signed: [keys: [key]]]` (see
`ImagePipe.child_spec/1`).

The configuration belongs to the instance, so with `:instance` a mount
accepts only the mount options below and `:mount`. Other options raise
`ArgumentError`. A request to a mount whose
instance isn't running, or whose `:mount` the instance doesn't define, raises
`ArgumentError`.

* `:instance` (`t:atom/0`) - Required. Name of a running instance (see `ImagePipe.child_spec/1`) whose configuration the mount serves.

* `:mount` (`t:atom/0`) - Name of one of the instance's `:mounts`, whose URL options check request URLs. Defaults to the instance's own URL options.

## Mount options

These apply to one mount, inline or on an instance.

* `:allow_origin` (`t:String.t/0`) - CORS origin sent in `Access-Control-Allow-Origin`, such as `"https://app.example.com"` or `"*"`. Scripts on that origin can read every response header, such as `ETag` and `Content-Disposition`, and send any request header except `Authorization`. Scripts can't read responses to requests sent with cookies. Without it, responses carry no CORS headers.

* `:allow_debug_headers` (`t:boolean/0`) - Lets a request's `debug` option add diagnostic headers to the response. See [debug headers](debug_headers.md). The default value is `false`.

* `:http_cache` - Which HTTP cache headers responses carry. See [HTTP cache headers](cdn-http-cache.md#header-modes). The default value is `:validators`.

`init/1` validates the options. An instance mount looks up its instance and
`:mount` per request.

---

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