Image.Plug.Options (image_plug v0.1.0)

Copy Markdown View Source

Validated, frozen configuration for Image.Plug.

Built once at compile/boot time by Image.Plug.init/1. The request path then only reads struct fields.

Construct with new!/1. Direct struct construction is discouraged — the validator enforces invariants such as "the provider module must export parse/2" that are not visible from the struct shape alone.

Summary

Types

module_with_options()
signing_options()

Signing configuration. nil disables signing entirely.

t()

Functions

new!(options)

Validates a keyword list and returns an Image.Plug.Options struct.

Types

module_with_options()

@type module_with_options() :: {module(), keyword()}

signing_options()

@type signing_options() ::
  nil | %{:keys => [String.t(), ...], optional(:required?) => boolean()}

Signing configuration. nil disables signing entirely.

When set, every request URL is verified against the configured :keys list (HMAC-SHA256). When :required? is true, an unsigned URL produces :signature_required. When :required? is false, unsigned URLs pass through but a signed URL with an invalid signature still 401s — defense in depth.

t()

@type t() :: %Image.Plug.Options{
  max_pixels: pos_integer(),
  on_error: Image.Plug.Pipeline.on_error(),
  provider: module(),
  provider_options: keyword(),
  request_timeout: pos_integer(),
  signing: signing_options(),
  source_resolver: module(),
  source_resolver_options: keyword(),
  telemetry_prefix: [atom(), ...],
  variant_store: module(),
  variant_store_options: keyword()
}

Functions

new!(options)

@spec new!(keyword()) :: t()

Validates a keyword list and returns an Image.Plug.Options struct.

Arguments

  • options is a keyword list. The :provider and :source_resolver keys are required. Each must be a {module, options} tuple.

Options

  • :provider (required) — {module, options} for an Image.Plug.Provider implementation.

  • :source_resolver (required) — {module, options} for an Image.Plug.SourceResolver implementation.

  • :variant_store — {module, options} for an Image.Plug.VariantStore implementation. Defaults to {Image.Plug.VariantStore.ETS, []}.

  • :on_error — error policy atom or {:status, code} tuple. Defaults to :auto.

  • :max_pixels — soft upper bound on the output pixel count. Defaults to 25_000_000.

  • :request_timeout — total per-request budget in milliseconds. Defaults to 10_000.

  • :telemetry_prefix — list of atoms prepended to telemetry event names. Defaults to [:image_plug].

Returns

Examples

iex> defmodule TestProv do
...>   @behaviour Image.Plug.Provider
...>   @impl true
...>   def parse(_conn, _options), do: {:error, Image.Plug.Error.new(:not_implemented, "test")}
...> end
iex> defmodule TestRes do
...>   @behaviour Image.Plug.SourceResolver
...>   @impl true
...>   def load(_source, _options), do: {:error, Image.Plug.Error.new(:not_implemented, "test")}
...> end
iex> options = Image.Plug.Options.new!(
...>   provider: {TestProv, []},
...>   source_resolver: {TestRes, []}
...> )
iex> options.provider
TestProv
iex> options.on_error
:auto