Serialises a transformed Vix.Vips.Image into bytes for the HTTP response.

Returns {:ok, body, content_type} where body is one of:

• {:stream, Enumerable.t()} — preferred. Backed by Image.stream!/2, which wraps Vix.Vips.Image.write_to_stream/2 so libvips emits encoded bytes chunk-by-chunk.

• {:bytes, iodata()} — fallback for callers that need the response fully buffered (HEAD requests, hosts that disable chunked transfer, the format=json output).

Canonical streaming pipeline

The full source-to-client chain mirrors the canonical shape documented in the Image library's stream test suite:

path
|> File.stream!(2048, [])      # Image.Plug.SourceResolver.File
|> Image.open()                # ditto
|> ...transforms...            # Image.Plug.Pipeline.Interpreter
|> Image.stream!(suffix: ext)  # this module's `:stream` body
|> Enum.reduce_while(conn, fn chunk, conn ->
     case Plug.Conn.chunk(conn, chunk) do
       {:ok, conn}      -> {:cont, conn}
       {:error, :closed} -> {:halt, conn}
     end
   end)                        # Image.Plug.Plug.send_body/4

Image.write(image, conn, suffix: ext) does the chunked-write loop internally and is functionally identical to that reduce_while block. We keep the loop in our own plug so we retain explicit control over the conn for header manipulation, error fallbacks, and telemetry.

Format support

Supports JPEG (baseline + progressive), PNG, WebP, AVIF, TIFF, JP2, GIF, PDF, the Accept-driven :auto selection, and the small :json metadata endpoint.

AVIF fallback

If libvips lacks AVIF write support, requests for format=avif encode to WebP and the response is tagged with the x-image-plug-format-fallback: avif->webp header. The plug forwards the header set by the encoder. Detection runs once at application boot via Image.Plug.Capabilities.probe/0.