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
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.
Callbacks
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()
© 2013 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/plug/Plug.html