Plug.Parsers behaviour

A plug for parsing the request body.

This module also specifies a behaviour that all the parsers to be used with Plug should adopt.

Options

All options supported by Plug.Conn.read_body/2 are also supported here (for example the :length option which specifies the max body length to read).

Examples

plug Plug.Parsers, parsers: [:urlencoded, :multipart]
plug Plug.Parsers, parsers: [:urlencoded, :json],
                   pass:  ["text/*"],
                   json_decoder: Poison

Built-in parsers

Plug ships with the following parsers:

This plug will raise Plug.Parsers.UnsupportedMediaTypeError by default if the request cannot be parsed by any of the given types and the MIME type has not been explicity accepted with the :accept option.

Plug.Parsers.RequestTooLargeError will be raised if the request goes over the given limit.

Parsers may raise a Plug.Parsers.ParseError if the request has a malformed body.

File handling

If a file is uploaded via any of the parsers, Plug will stream the uploaded contents to a file in a temporary directory in order to avoid loading the whole file into memory. For such, the :plug application needs to be started in order for file uploads to work. More details on how the uploaded file is handled can be found in the documentation for Plug.Upload.

When a file is uploaded, the request parameter that identifies that file will be a Plug.Upload struct with informations about the uploaded file (e.g., filename and content type) and about where the file is stored.

The temporary directory where files are streamed to can be customized by setting the PLUG_TMPDIR environment variable on the host system. If PLUG_TMPDIR isn’t set, Plug will look at some environment variables which usually hold the value of the system’s temporary directory (like TMPDIR or TMP). If no value is found in any of those variables, /tmp is used as a default.

Source

Summary

call(conn, opts)

Callback implementation for Plug.call/2

init(opts)

Callback implementation for Plug.init/1

Functions

call(conn, opts)

Callback implementation for Plug.call/2.

Source
init(opts)

Callback implementation for Plug.init/1.

Source

Callbacks

parse/5

Specs:

Attempts to parse the connection’s request body given the content-type type and subtype and the headers. Returns:

  • {:ok, conn} if the parser is able to handle the given content-type
  • {:error, :too_large, conn} if the request goes over the given limit

subtype and headers. Returns {:ok, conn} if the parser can handle the given content type, {:halt, conn} otherwise.

Source