Plug behaviour

The plug specification.

There are two kind of plugs: function plugs and module plugs.

Function plugs

A function plug is any function that receives a connection and a set of options and returns a connection. Its type signature must be:

(Plug.Conn.t, Plug.opts) :: Plug.Conn.t

Module plugs

A module plug is an extension of the function plug. It is a module that must export:

a call/2 function with the signature defined above
an init/1 function which takes a set of options and initializes it.

The result returned by init/1 is passed as second argument to call/2. Note that init/1 may be called during compilation and as such it must not return pids, ports or values that are specific to the runtime.

The API expected by a module plug is defined as a behaviour by the Plug module (this module).

Examples

Here's an example of a function plug:

def json_header_plug(conn, opts) do
  Plug.Conn.put_resp_content_type(conn, "application/json")
end

Here's an example of a module plug:

defmodule JSONHeaderPlug do
  import Plug.Conn

  def init(opts) do
    opts
  end

  def call(conn, _opts) do
    put_resp_content_type(conn, "application/json")
  end
end

The Plug pipeline

The Plug.Builder module provides conveniences for building plug pipelines.

Summary

Types

opts()

Functions

forward(conn, new_path, target, opts): Forwards requests to another Plug setting the connection to a trailing subpath of the request.
run(conn, plugs, opts \\ []): Run a series of Plugs at runtime.

Types

opts()

Specs

opts() ::
  binary()
  | tuple()
  | atom()
  | integer()
  | float()
  | [opts()]
  | %{optional(opts()) => opts()}
  | MapSet.t()

Functions

forward(conn, new_path, target, opts)

Specs

forward(Plug.Conn.t(), [String.t()], atom(), opts()) :: Plug.Conn.t()

Forwards requests to another Plug setting the connection to a trailing subpath of the request.

The path_info on the forwarded connection will only include the trailing segments of the request path supplied to forward, while conn.script_name will retain the correct base path for e.g. url generation.

Example

defmodule Router do
  def init(opts), do: opts

  def call(conn, opts) do
    case conn do
      # Match subdomain
      %{host: "admin." <> _} ->
        AdminRouter.call(conn, opts)

      # Match path on localhost
      %{host: "localhost", path_info: ["admin" | rest]} ->
        Plug.forward(conn, rest, AdminRouter, opts)

      _ ->
        MainRouter.call(conn, opts)
    end
  end
end

run(conn, plugs, opts \\ [])

Specs

run(
  Plug.Conn.t(),
  [{module(), opts()} | (Plug.Conn.t() -> Plug.Conn.t())],
  Keyword.t()
) :: Plug.Conn.t()

Run a series of Plugs at runtime.

The plugs given here can be either a tuple, representing a module plug and their options, or a simple function that receives a connection and returns a connection.

If any of the plugs halt, the remaining plugs are not invoked. If the given connection was already halted, none of the plugs are invoked either.

While Plug.Builder works at compile-time, this is a straight-forward alternative that works at runtime.

Examples

Plug.run(conn, [{Plug.Head, []}, IO.inspect/1])

Options

:log_on_halt - a log level to be used if a Plug halts

Callbacks

call(arg1, opts)

Specs

call(Plug.Conn.t(), opts()) :: Plug.Conn.t()

init(opts)

Specs

init(opts()) :: opts()