Image.Plug.Provider.Cloudflare.URL (image_plug v0.1.0)

URL-shape recognition for the Cloudflare Images URL grammar.

Two forms are recognised:

Remote-image transform

/cdn-cgi/image/<options>/<source>

Where <source> is either an absolute path (/foo/bar.jpg) or an absolute URL (http://... or https://...). Always recognised.

Hosted-image delivery

/<account_hash>/<image-id>/<variant-or-options>

Recognised when the provider is configured with :hosted_account_hash. The trailing segment is treated as a variant name iff it contains no = character (matching Cloudflare's documented rule); otherwise it is parsed as an options string. An empty trailing segment maps to the implicit "public" variant.

This module does not interpret the options string — that is Image.Plug.Provider.Cloudflare.Options' job — and it does not load any source bytes.

Summary

Types

recognised()

The recognised URL shape, ready for the options parser and the source resolver.

Functions

parse(conn, options)

Parses the request path of a Plug.Conn into a recognised URL shape.

Types

recognised()

@type recognised() :: %{
  shape: :remote | :hosted,
  options: String.t() | nil,
  variant: String.t() | nil,
  source: Image.Plug.Source.t()
}

The recognised URL shape, ready for the options parser and the source resolver.

:shape — :remote (cdn-cgi form) or :hosted (delivery form).
:options — an options string. nil for the hosted form when the trailing segment was a variant name.
:variant — a variant name. nil for the remote form and for the hosted form when the trailing segment looked like options.
:source — the Image.Plug.Source derived from the URL.

Functions

parse(conn, options)

@spec parse(
  Plug.Conn.t(),
  keyword()
) :: {:ok, recognised()} | {:error, Image.Plug.Error.t()}

Parses the request path of a Plug.Conn into a recognised URL shape.

Arguments

conn is a Plug.Conn struct.
options is a keyword list. The following keys are honoured:

Options

:mount — string path prefix that the plug is mounted under. Stripped before pattern matching. Defaults to "".
:hosted_account_hash — when set, also recognise /<this-hash>/<image-id>/<tail>. Defaults to nil.

Returns

{:ok, recognised} on a successful match.
{:error, %Image.Plug.Error{tag: :malformed_url}} when the path does not match either form.
{:error, %Image.Plug.Error{tag: :invalid_option}} when the source segment is malformed.

Examples

iex> conn = %Plug.Conn{
...>   path_info: ["cdn-cgi", "image", "width=200", "foo", "bar.jpg"],
...>   request_path: "/cdn-cgi/image/width=200/foo/bar.jpg"
...> }
iex> {:ok, %{shape: :remote, options: "width=200", source: source}} =
...>   Image.Plug.Provider.Cloudflare.URL.parse(conn, [])
iex> source.kind
:path

iex> conn = %Plug.Conn{
...>   path_info: ["acct123", "img456", "thumbnail"],
...>   request_path: "/acct123/img456/thumbnail"
...> }
iex> {:ok, parsed} =
...>   Image.Plug.Provider.Cloudflare.URL.parse(conn,
...>     hosted_account_hash: "acct123"
...>   )
iex> {parsed.shape, parsed.variant, parsed.source.ref}
{:hosted, "thumbnail", {"acct123", "img456"}}