Image.Plug.Provider behaviour (image_plug v0.1.0)

Copy Markdown View Source

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 parse/2.

Summary

Types

info_kind()

The shape returned by parse/2 on success.

override()

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()

Callbacks

parse(t, options)

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

Types

info_kind()

@type info_kind() :: :iiif_image_info

The shape returned by 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()

@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()

@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()}

Callbacks

parse(t, options)

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

Parses a request into one of the 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.